@bongos/core 1.17.0

package/scripts/gds/build-bongos.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// scripts/gds/build-bongos.js — compile the standalone `bongos` CLI binaries
+// (GDS-V4 · V4.R81 · task 1248). CI (.github/workflows/build-bongos-cli.yml) runs
+// this; a maintainer can run it locally too.
+//
+// Uses `bun build --compile`, which CROSS-compiles every target from a single
+// host (mac arm64/x64, linux x64/arm64, windows x64) — no per-OS runner matrix.
+// The binary is fully self-contained: no Node, no repo needed at runtime. The
+// on-ramp verbs (login/box/shell/code/init/reauth) are bundled + dispatched
+// in-process by bin/bongos.js (its COMPILED branch); work verbs print how to get
+// a real environment.
+//
+//   node scripts/gds/build-bongos.js                 # all targets → dist/
+//   node scripts/gds/build-bongos.js --target mac-arm64
+//   node scripts/gds/build-bongos.js --outdir /tmp/out
+//
+// Output filenames match config/bongos-cli.json's `assets` exactly (so the
+// /downloads/bongos redirects resolve after `gh release create`). Version comes
+// from that same config — the single source of truth for a release.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { arg } = require('./cli-lib');
+
+const REPO_ROOT = path.join(__dirname, '..', '..');
+const ENTRY = path.join(REPO_ROOT, 'bin', 'bongos.js');
+const cfg = require(path.join(REPO_ROOT, 'config', 'bongos-cli.json'));
+const VERSION = cfg.version;
+
+// target key (matches config assets) → { bunTarget, asset filename }
+const TARGETS = {
+  'mac-arm64': { bun: 'bun-darwin-arm64', file: cfg.assets['mac-arm64'] },
+  'mac-x64': { bun: 'bun-darwin-x64', file: cfg.assets['mac-x64'] },
+  'linux-x64': { bun: 'bun-linux-x64', file: cfg.assets['linux-x64'] },
+  'linux-arm64': { bun: 'bun-linux-arm64', file: cfg.assets['linux-arm64'] },
+  'win-x64': { bun: 'bun-windows-x64', file: cfg.assets['win-x64'] },
+};
+
+function bunPresent() {
+  const r = spawnSync('bun', ['--version'], { encoding: 'utf8', shell: process.platform === 'win32' });
+  return !!r && !r.error && r.status === 0;
+}
+
+function build(one, outDir) {
+  const t = TARGETS[one];
+  if (!t) throw new Error(`unknown target "${one}" (known: ${Object.keys(TARGETS).join(', ')})`);
+  if (!t.file) throw new Error(`config/bongos-cli.json has no asset for target "${one}"`);
+  const outfile = path.join(outDir, t.file);
+  console.log(`  building ${one} → ${path.relative(REPO_ROOT, outfile)} (${t.bun})`);
+  const r = spawnSync(
+    'bun',
+    ['build', '--compile', `--target=${t.bun}`, ENTRY, '--outfile', outfile],
+    { stdio: 'inherit', cwd: REPO_ROOT, shell: process.platform === 'win32' }
+  );
+  if (!r || r.error || r.status !== 0) {
+    throw new Error(`bun build failed for ${one}${r && r.error ? `: ${r.error.message}` : ` (exit ${r ? r.status : '?'})`}`);
+  }
+  return outfile;
+}
+
+function main() {
+  if (!bunPresent()) {
+    console.error('✖ `bun` is required to compile the standalone binary but was not found.');
+    console.error('  Install it (https://bun.sh) — e.g. `curl -fsSL https://bun.sh/install | bash` —');
+    console.error('  or in CI use the oven-sh/setup-bun action. Then re-run.');
+    process.exit(1);
+  }
+  const outDir = arg('--outdir') || path.join(REPO_ROOT, 'dist');
+  fs.mkdirSync(outDir, { recursive: true });
+  const only = arg('--target');
+  const targets = only ? [only] : Object.keys(TARGETS);
+
+  console.log(`bongos build — version ${VERSION}, ${targets.length} target(s) → ${path.relative(REPO_ROOT, outDir) || '.'}`);
+  const built = [];
+  for (const t of targets) built.push(build(t, outDir));
+
+  console.log(`\n✓ Built ${built.length} binary(ies):`);
+  for (const f of built) {
+    let size = '';
+    try { size = ` (${(fs.statSync(f).size / 1e6).toFixed(1)} MB)`; } catch { /* ignore */ }
+    console.log(`  ${path.relative(REPO_ROOT, f)}${size}`);
+  }
+  console.log('\nNext: publish these as assets on a `v' + VERSION + '` release of the public releases repo');
+  console.log('(config/bongos-cli.json → releases_repo). See docs/recipes/bongos-cli-release.md.');
+}
+
+if (require.main === module) {
+  try { main(); } catch (e) { console.error(`✖ ${e.message}`); process.exit(1); }
+}
+
+module.exports = { TARGETS, VERSION };

package/scripts/gds/capture.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+// Capture an idea into idea_inbox (the structured replacement for
+// generative-ideas.md).
+//
+// Usage:
+//   node scripts/gds/capture.js "title" \
+//     [--kind feature] \
+//     [--body-file path] \
+//     [--version V1|PMS-V2|GDS-V3] \
+//     [--priority N]
+//
+// Defaults:
+//   --kind     → server auto-classifies from title+body (keyword heuristics
+//                today; replaced by the real classifier when task B1 ships)
+//   --version  → most recent version with status='building' (queried from
+//                /api/gds/versions); leave null if there isn't one
+//   --priority → null (set later at triage time)
+//
+// Exit codes:
+//   0  captured
+//   1  api / network error
+//   2  bad invocation
+//
+// Acceptance examples (from task #34 spec):
+//   $ node scripts/gds/capture.js "we should add a 'last 24 hours' filter to the public dashboard"
+//   📥 Captured idea #12: kind=feature (auto), version=PMS-V2, priority=null
+//   Inbox now: 8 open
+
+const fs = require('node:fs/promises');
+const { cliClient, requireSession, arg } = require('./cli-lib');
+
+
+async function resolveDefaultVersion() {
+  const api = await cliClient();
+  const r = await api.versions.getVersions();
+  if (!r.ok) return null;
+  const versions = r.data?.versions ?? [];
+  // Most recent building version. Fall back to any building version if
+  // started_at is null on all of them.
+  const building = versions.filter((v) => v.status === 'building');
+  if (building.length === 0) return null;
+  building.sort((a, b) => {
+    const ta = a.started_at ? new Date(a.started_at).getTime() : 0;
+    const tb = b.started_at ? new Date(b.started_at).getTime() : 0;
+    return tb - ta;
+  });
+  return building[0].id;
+}
+
+async function main() {
+  await requireSession();
+  const args = process.argv.slice(2);
+  const title = args[0];
+  if (!title || title.startsWith('--')) {
+    console.error('usage: node scripts/gds/capture.js "title" [--kind feature] [--body-file path] [--version V1|PMS-V2] [--priority N]');
+    process.exit(2);
+  }
+
+  const kindFromArg = arg('--kind', args);
+  const bodyFile = arg('--body-file', args);
+  const versionFromArg = arg('--version', args);
+  const priorityStr = arg('--priority', args);
+
+  let bodyMd = '';
+  if (bodyFile) {
+    try {
+      bodyMd = await fs.readFile(bodyFile, 'utf8');
+    } catch (err) {
+      console.error(`failed to read --body-file: ${err.message}`);
+      process.exit(2);
+    }
+  }
+
+  let priority = null;
+  if (priorityStr != null) {
+    const p = Number(priorityStr);
+    if (!Number.isInteger(p) || p < 1 || p > 5) {
+      console.error(`--priority must be an integer 1..5 (got ${priorityStr})`);
+      process.exit(2);
+    }
+    priority = p;
+  }
+
+  const version = versionFromArg || (await resolveDefaultVersion());
+
+  const payload = {
+    title,
+    body_md: bodyMd,
+    suggested_version: version,
+    suggested_priority: priority,
+  };
+  if (kindFromArg) payload.kind = kindFromArg;
+
+  const api = await cliClient();
+  const r = await api.inbox.postInbox({ body: payload });
+  if (!r.ok) {
+    console.error(`capture failed (${r.status}):`, r.data);
+    process.exit(1);
+  }
+
+  const { idea, open_count, kind_auto } = r.data;
+  const kindLabel = kind_auto ? `${idea.kind} (auto)` : idea.kind;
+  const versionLabel = idea.suggested_version || 'none';
+  const priorityLabel = idea.suggested_priority == null ? 'null' : `P${idea.suggested_priority}`;
+
+  console.log(
+    `Captured idea #${idea.id}: kind=${kindLabel}, version=${versionLabel}, priority=${priorityLabel}`
+  );
+  console.log(`Inbox now: ${open_count} open`);
+
+  // Migration detection lives only on the server now (POST /api/gds/tasks sets
+  // tasks.needs_migration from the title/description on create — migration 081,
+  // task 876). Ideas carry no touches[] and aren't tasks, so the old CLI-side
+  // "keep 'migrations/' in touches[]" hint was removed with the sentinel it
+  // referred to; promotion to a task re-runs the detection automatically.
+}
+
+if (require.main === module) {
+  main().catch((err) => {
+    console.error('fatal:', err);
+    process.exit(1);
+  });
+}

package/scripts/gds/cf-tunnel.js

@@ -0,0 +1,419 @@
+// scripts/gds/cf-tunnel.js — a thin Cloudflare API client for the box terminal's
+// NAMED tunnel (#771, ADR 0038 Part B). A control-plane (operator-CLI) network
+// client; moved here from modules/dev-box/ alongside do-api.js so the control
+// plane owns the network clients and the shared http-api-client (task #1943).
+//
+// The control-plane half of the "named tunnel" production upgrade. #760 shipped
+// the BOX-side cloudflared-run.sh that already runs a named tunnel when
+// BOX_TUNNEL_TOKEN + BOX_TERMINAL_HOSTNAME are present in /etc/otb/box.env. This
+// module is how scripts/gds/box.js MAKES those exist: it creates (or reuses) a
+// remotely-managed Cloudflare Tunnel per builder, points its ingress at the box's
+// localhost ttyd (127.0.0.1:7681), routes a stable DNS CNAME
+// (term-<login>.amazonprimea.com → <tunnel-id>.cfargotunnel.com), and hands
+// back the connector token to bake into the box. Teardown deletes the tunnel +
+// the DNS record.
+//
+// Design mirrors src/bongos/do-api.js exactly so the box subsystem has ONE shape for
+// every external API:
+//   - Injectable transport (`fetchImpl`) so tests assert request shape with a
+//     fake fetch and never touch the network.
+//   - `dryRun` mode (the CLI DEFAULT): NO request is sent; each method logs what
+//     it WOULD do and returns a synthetic `{ dryRun: true, ... }` so box.js's
+//     control flow runs end-to-end against a throwaway plan.
+//   - Live mode requires a token + accountId; the constructor throws clearly if
+//     asked to run live without them — it never silently no-ops a real call.
+//
+// SECURITY: the Cloudflare API token (Account:Cloudflare Tunnel:Edit +
+// Zone:DNS:Edit) lives ONLY on the control plane (the prod droplet's box.env),
+// exactly where DO_API_TOKEN lives — never on the internet-facing web tier. A
+// web-tier compromise can never create or delete a tunnel. The per-builder
+// connector token this returns is baked into the box's cloud-init (same exposure
+// as the SSH keys already baked there) and only authorizes running THAT tunnel,
+// whose only target is the basic-auth-protected localhost ttyd.
+
+const { JsonHttpApi, makeApiError } = require('./http-api-client');
+
+const CF_API_BASE = 'https://api.cloudflare.com/client/v4';
+const CFARGO_SUFFIX = 'cfargotunnel.com';
+const TTYD_SERVICE = 'http://127.0.0.1:7681';
+// The box's own `node server.js` (ADR 0044). A SECOND ingress route on the same
+// per-builder named tunnel exposes the live game preview at game-<login>.<apex>.
+const GAME_SERVICE = 'http://127.0.0.1:3000';
+
+// SECURITY (#919, security_reports SR#11): the apex gds_session cookie
+// (Domain=.amazonprimea.com) is sent by the browser to every subdomain, including
+// the box-fronting term-<login> (ttyd) and sandbox-<login> (game preview) hosts —
+// so the builder's FULL hall bearer rides the tunnel onto the box, which is OUTSIDE
+// the ADR 0016 trust boundary. We must NOT narrow the apex cookie (the #726 SSO
+// across builders.amazonprimea.com needs it), so instead a zone Transform Rule
+// removes the Cookie REQUEST header at the Cloudflare edge — before the request
+// enters the tunnel — for exactly the box subdomains. ttyd uses basic-auth and the
+// sandbox serves the game, so neither needs the cookie. Cloudflare permits REMOVE
+// (not set/modify) of the Cookie request header via Transform Rules.
+const COOKIE_STRIP_PHASE = 'http_request_late_transform';
+const COOKIE_STRIP_RULE_DESC = 'otb-919 strip Cookie on box subdomains (term-*/sandbox-*) — SR#11';
+// Zone-scoped ruleset ⇒ http.host is always within amazonprimea.com, so the prefix
+// match precisely targets the per-builder box hosts and nothing else.
+const COOKIE_STRIP_EXPRESSION = 'starts_with(http.host, "term-") or starts_with(http.host, "sandbox-")';
+
+// #1065 — Cloudflare's DEFAULT 4h Browser Cache TTL rewrites the box origin's
+// no-store on the sandbox hosts, serving multi-hour-stale game code. A zone Cache
+// Rule scoped to sandbox-* bypasses the edge cache + respects the origin headers
+// there, WITHOUT touching the zone-wide TTL prod (the apex) relies on. Like the
+// cookie-strip rule, this needs the CF token to carry zone "Cache Rules" (Account
+// Rulesets) edit scope; callers run it best-effort so a missing scope warns.
+const CACHE_BYPASS_PHASE = 'http_request_cache_settings';
+const CACHE_BYPASS_RULE_DESC = 'otb-1065 bypass cache on sandbox preview hosts (sandbox-*) — keep prod cached';
+// Sandbox preview only. NOT term-* (ttyd, not cached) and NEVER the apex.
+const CACHE_BYPASS_EXPRESSION = 'starts_with(http.host, "sandbox-")';
+
+// FORCE IPv4 egress. The Cloudflare API token is IP-locked to the control-plane
+// droplet's IPv4 (least privilege, mirroring box-dns-cloudflare.sh's `curl -4`).
+// The droplet ALSO has IPv6 egress, and Node's fetch will happily dial Cloudflare
+// over IPv6 — whose source address is NOT on the token's allow-list, so Cloudflare
+// rejects it as an "Authentication error" (verified live under #771). undici's
+// Agent with connect.family=4 pins IPv4. Memoized; degrades to undefined (default
+// dispatcher) if undici can't be required, so a non-IP-locked token still works.
+let _ipv4Dispatcher;
+let _ipv4Tried = false;
+function ipv4Dispatcher() {
+  if (_ipv4Tried) return _ipv4Dispatcher;
+  _ipv4Tried = true;
+  try {
+    // eslint-disable-next-line global-require
+    const { Agent } = require('undici');
+    _ipv4Dispatcher = new Agent({ connect: { family: 4 } });
+  } catch { _ipv4Dispatcher = undefined; }
+  return _ipv4Dispatcher;
+}
+
+const CfApiError = makeApiError('CfApiError', 'CF_API_ERROR');
+
+// Deterministic per-builder names so teardown can find what provision created
+// WITHOUT persisting an id in the DB (no migration): the tunnel name and the DNS
+// hostname are both pure functions of the login.
+function tunnelName(login) { return `otb-term-${login}`; }
+function terminalHostname(login, zone) { return `term-${login}.${zone}`; }
+// The live game preview host (ADR 0044) — the builder's "sandbox". One label
+// under the apex (same zone as the terminal host) so free Universal SSL covers
+// it — see the #771 lesson that forced an apex one-label host over `dev.*`.
+function previewHostname(login, zone) { return `sandbox-${login}.${zone}`; }
+
+class CfTunnelApi extends JsonHttpApi {
+  // opts: { token, accountId, dryRun=true, fetchImpl=globalThis.fetch, base, log }
+  constructor(opts = {}) {
+    super(opts, { base: CF_API_BASE, logTag: 'CF', ErrorClass: CfApiError });
+    this.accountId = opts.accountId || null;
+    // Pin IPv4 for the live token (see ipv4Dispatcher). Overridable/null-able for
+    // tests; a fake fetchImpl simply ignores the extra `dispatcher` option.
+    this.dispatcher = opts.dispatcher !== undefined ? opts.dispatcher : ipv4Dispatcher();
+    if (!this.dryRun) {
+      if (!this.token) {
+        throw new CfApiError(
+          'live Cloudflare call requested but no API token is set — ' +
+          'set CLOUDFLARE_API_TOKEN (Tunnel + DNS scope) or run without --apply (dry-run)'
+        );
+      }
+      if (!this.accountId) {
+        throw new CfApiError('live Cloudflare tunnel call requested but CLOUDFLARE_ACCOUNT_ID is not set');
+      }
+      if (typeof this.fetchImpl !== 'function') {
+        throw new CfApiError('no fetch implementation available for live mode');
+      }
+    }
+  }
+
+  // CfTunnelApi pins the IPv4 dispatcher on every live request (its token is
+  // IP-locked, #771) and treats the Cloudflare {success:false} envelope as a
+  // failure, not just a non-2xx status. The dry-run/live skeleton itself (and the
+  // envelope's {result} passthrough) is inherited from JsonHttpApi.
+  requestInit() { return { dispatcher: this.dispatcher }; }
+
+  detectError(res, json) {
+    if (!res.ok || (json && json.success === false)) {
+      const errs = json && Array.isArray(json.errors) ? json.errors.map((e) => e.message || e.code).join('; ') : '';
+      return errs || `HTTP ${res.status}`;
+    }
+    return null;
+  }
+
+  // ---- tunnels (account-scoped) ---------------------------------------------
+
+  // Find a non-deleted tunnel by exact name. Returns the tunnel object or null.
+  async findTunnelByName(name) {
+    const r = await this._req('GET', `/accounts/${this.accountId}/cfd_tunnel?name=${encodeURIComponent(name)}&is_deleted=false`, null, {
+      dryRunResult: { result: [] },
+    });
+    const list = (r && r.result) || [];
+    return list.find((tn) => tn.name === name) || null;
+  }
+
+  // Create a remotely-managed tunnel (config_src: 'cloudflare' so the ingress is
+  // set via the API, not a config file on the box). Returns the tunnel object.
+  async createTunnel(name) {
+    const r = await this._req('POST', `/accounts/${this.accountId}/cfd_tunnel`, { name, config_src: 'cloudflare' }, {
+      dryRunResult: { result: { id: `dryrun-tunnel-${name}`, name } },
+    });
+    return (r && r.result) || null;
+  }
+
+  // Find-or-create. Idempotent: re-provisioning a builder reuses their tunnel.
+  async ensureTunnel(name) {
+    const existing = await this.findTunnelByName(name);
+    if (existing) { this.log(`reusing tunnel ${existing.id} (${name})`); return { tunnel: existing, created: false }; }
+    const tunnel = await this.createTunnel(name);
+    this.log(`created tunnel ${tunnel && tunnel.id} (${name})`);
+    return { tunnel, created: true };
+  }
+
+  // The connector token (the BOX_TUNNEL_TOKEN the box runs cloudflared with).
+  async getTunnelToken(tunnelId) {
+    const r = await this._req('GET', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}/token`, null, {
+      dryRunResult: { result: `dryrun-token-${tunnelId}` },
+    });
+    return (r && r.result) || null;
+  }
+
+  // Point the tunnel's ingress at the box's localhost ttyd, with a 404 catch-all.
+  // `extraRoutes` ([{ hostname, service }, ...]) adds further hostname→service
+  // rules on the SAME connector — e.g. the ADR 0044 game preview at
+  // sandbox-<login>.<apex> → 127.0.0.1:3000 — inserted before the catch-all. A
+  // Cloudflare named tunnel routes by hostname, so each route needs its own
+  // proxied DNS CNAME (see ensureNamedTunnel).
+  async putConfiguration(tunnelId, { hostname, service = TTYD_SERVICE, extraRoutes = [] } = {}) {
+    const ingress = [{ hostname, service }, ...extraRoutes, { service: 'http_status:404' }];
+    const config = { ingress };
+    return this._req('PUT', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}/configurations`, { config }, {
+      dryRunResult: { result: { config } },
+    });
+  }
+
+  // Best-effort: drop any live connector connections so the tunnel can be deleted
+  // (CF refuses to delete a tunnel with active connections). The droplet is
+  // already gone by teardown time, so this is usually a no-op.
+  async cleanupConnections(tunnelId) {
+    return this._req('DELETE', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}/connections`, null, {
+      dryRunResult: { result: {} },
+    });
+  }
+
+  async deleteTunnel(tunnelId) {
+    return this._req('DELETE', `/accounts/${this.accountId}/cfd_tunnel/${tunnelId}`, null, {
+      dryRunResult: { result: { id: tunnelId } },
+    });
+  }
+
+  // ---- DNS (zone-scoped) -----------------------------------------------------
+
+  async getZoneId(zone) {
+    const r = await this._req('GET', `/zones?name=${encodeURIComponent(zone)}`, null, {
+      dryRunResult: { result: [{ id: `dryrun-zone-${zone}` }] },
+    });
+    const z = ((r && r.result) || [])[0];
+    if (!z || !z.id) throw new CfApiError(`Cloudflare zone '${zone}' not found, or the token lacks access to it`);
+    return z.id;
+  }
+
+  async findDnsRecord(zoneId, name) {
+    const r = await this._req('GET', `/zones/${zoneId}/dns_records?type=CNAME&name=${encodeURIComponent(name)}`, null, {
+      dryRunResult: { result: [] },
+    });
+    const lower = name.toLowerCase();
+    return (((r && r.result) || []).find((rec) => rec.name.toLowerCase() === lower)) || null;
+  }
+
+  // Upsert the proxied CNAME that fronts the tunnel. proxied:true is required for
+  // a *.cfargotunnel.com target (the orange-cloud is what routes to the tunnel).
+  async upsertDnsRoute({ zoneId, name, tunnelId }) {
+    const body = { type: 'CNAME', name, content: `${tunnelId}.${CFARGO_SUFFIX}`, proxied: true, ttl: 1 };
+    const existing = await this.findDnsRecord(zoneId, name);
+    if (existing) {
+      return this._req('PUT', `/zones/${zoneId}/dns_records/${existing.id}`, body, {
+        dryRunResult: { result: { id: existing.id, ...body } },
+      });
+    }
+    return this._req('POST', `/zones/${zoneId}/dns_records`, body, {
+      dryRunResult: { result: { id: `dryrun-dns-${name}`, ...body } },
+    });
+  }
+
+  async deleteDnsRoute({ zoneId, name }) {
+    const existing = await this.findDnsRecord(zoneId, name);
+    if (!existing) return { result: null, missing: true };
+    return this._req('DELETE', `/zones/${zoneId}/dns_records/${existing.id}`, null, {
+      dryRunResult: { result: { id: existing.id } },
+    });
+  }
+
+  // ---- edge cookie strip (zone-scoped Transform Rule, #919 / SR#11) ----------
+
+  // Ensure the zone's request-header Transform Rule that REMOVES the Cookie header
+  // on the box subdomains (term-*/sandbox-*). Idempotent and NON-DESTRUCTIVE: it
+  // reads the phase entrypoint ruleset, preserves every OTHER transform rule, drops
+  // any prior copy of ours (matched by description), and PUTs the merged set. One
+  // wildcard-prefix rule covers every builder's box, so this only needs to land
+  // ONCE — but re-running on each provision self-heals a deleted rule. Requires the
+  // CF token to carry zone "Transform Rules" (Account Rulesets) edit scope; callers
+  // run it best-effort so a missing scope warns but never blocks box provisioning.
+  async ensureCookieStripRule({ zone }) {
+    const zoneId = await this.getZoneId(zone);
+    const phasePath = `/zones/${zoneId}/rulesets/phases/${COOKIE_STRIP_PHASE}/entrypoint`;
+    // Read the current entrypoint ruleset. A zone with no transform rules yet has
+    // no entrypoint (404) — fine, the PUT below creates it.
+    let existing = [];
+    try {
+      const got = await this._req('GET', phasePath, null, { dryRunResult: { result: { rules: [] } } });
+      const rules = got && got.result && got.result.rules;
+      existing = Array.isArray(rules) ? rules : [];
+    } catch (e) {
+      if (e.status && e.status !== 404) throw e;
+    }
+    const ourRule = {
+      action: 'rewrite',
+      action_parameters: { headers: { Cookie: { operation: 'remove' } } },
+      expression: COOKIE_STRIP_EXPRESSION,
+      description: COOKIE_STRIP_RULE_DESC,
+      enabled: true,
+    };
+    // Preserve other rules, dropping CF-managed read-only fields (id/version/
+    // last_updated) that a PUT rejects; keep a caller-set `ref` if present.
+    const preserved = existing
+      .filter((r) => r && r.description !== COOKIE_STRIP_RULE_DESC)
+      .map((r) => ({
+        action: r.action,
+        action_parameters: r.action_parameters,
+        expression: r.expression,
+        description: r.description,
+        enabled: r.enabled !== false,
+        ...(r.ref ? { ref: r.ref } : {}),
+      }));
+    const rules = [...preserved, ourRule];
+    return this._req('PUT', phasePath, { rules }, { dryRunResult: { result: { rules } } });
+  }
+
+  // ---- edge cache bypass on the sandbox hosts (zone Cache Rule, #1065) --------
+
+  // Ensure the zone Cache Rule that BYPASSES Cloudflare caching for the sandbox
+  // preview hosts (sandbox-*), so the box origin's no-store (#1065 part 1) is
+  // honored and the 4h Browser Cache TTL stops serving stale game code. Idempotent
+  // + NON-DESTRUCTIVE (mirrors ensureCookieStripRule): read the cache-phase
+  // entrypoint ruleset, preserve every OTHER cache rule, drop any prior copy of
+  // ours by description, PUT the merged set. Scoped strictly to sandbox-* via the
+  // host expression so prod (the apex) caching is UNTOUCHED. Requires the CF token
+  // to carry zone "Cache Rules" (Account Rulesets) edit scope; callers run it
+  // best-effort so a missing scope warns but never blocks provisioning.
+  async ensureCacheBypassRule({ zone }) {
+    const zoneId = await this.getZoneId(zone);
+    const phasePath = `/zones/${zoneId}/rulesets/phases/${CACHE_BYPASS_PHASE}/entrypoint`;
+    let existing = [];
+    try {
+      const got = await this._req('GET', phasePath, null, { dryRunResult: { result: { rules: [] } } });
+      const rules = got && got.result && got.result.rules;
+      existing = Array.isArray(rules) ? rules : [];
+    } catch (e) {
+      if (e.status && e.status !== 404) throw e;
+    }
+    const ourRule = {
+      action: 'set_cache_settings',
+      action_parameters: {
+        cache: false, // do not cache on the edge
+        // Even if a future tweak re-enables caching, honor the box origin's
+        // no-store and never override its browser TTL.
+        browser_ttl: { mode: 'respect_origin' },
+      },
+      expression: CACHE_BYPASS_EXPRESSION,
+      description: CACHE_BYPASS_RULE_DESC,
+      enabled: true,
+    };
+    const preserved = existing
+      .filter((r) => r && r.description !== CACHE_BYPASS_RULE_DESC)
+      .map((r) => ({
+        action: r.action,
+        action_parameters: r.action_parameters,
+        expression: r.expression,
+        description: r.description,
+        enabled: r.enabled !== false,
+        ...(r.ref ? { ref: r.ref } : {}),
+      }));
+    const rules = [...preserved, ourRule];
+    return this._req('PUT', phasePath, { rules }, { dryRunResult: { result: { rules } } });
+  }
+
+  // ---- high-level compose ----------------------------------------------------
+
+  // Create-or-reuse everything the box needs for a stable named tunnel and return
+  // the values to bake into /etc/otb/box.env. Idempotent end-to-end.
+  async ensureNamedTunnel({ login, zone, terminalZone }) {
+    const name = tunnelName(login);
+    const hostname = terminalHostname(login, terminalZone);
+    // The ADR 0044 live game preview rides the SAME tunnel as a second ingress
+    // route + its own proxied CNAME.
+    const previewHost = previewHostname(login, terminalZone);
+    const { tunnel, created } = await this.ensureTunnel(name);
+    const tunnelId = tunnel && tunnel.id;
+    await this.putConfiguration(tunnelId, {
+      hostname,
+      extraRoutes: [{ hostname: previewHost, service: GAME_SERVICE }],
+    });
+    const token = await this.getTunnelToken(tunnelId);
+    const zoneId = await this.getZoneId(zone);
+    await this.upsertDnsRoute({ zoneId, name: hostname, tunnelId });
+    await this.upsertDnsRoute({ zoneId, name: previewHost, tunnelId });
+    // SECURITY (#919 / SR#11): strip the apex cookie at the edge for the box
+    // subdomains. BEST-EFFORT — a CF token without Transform Rules scope must not
+    // block provisioning (the box still works; the rule is defense-in-depth). Warn
+    // loudly so the operator adds the scope or applies the rule once by hand.
+    try {
+      await this.ensureCookieStripRule({ zone });
+    } catch (e) {
+      this.log(`⚠ #919 cookie-strip Transform Rule NOT applied (${e.message}) — add zone "Transform Rules" scope to CLOUDFLARE_API_TOKEN or apply it once in the CF dashboard (ADR 0053)`);
+    }
+    // #1065: stop Cloudflare's 4h Browser Cache TTL from serving stale sandbox
+    // game code. BEST-EFFORT — a CF token without Cache-Rules scope must not block
+    // provisioning. Warn loudly so the operator adds the scope or applies the rule
+    // once by hand (operator blocker, like the cookie-strip rule).
+    try {
+      await this.ensureCacheBypassRule({ zone });
+    } catch (e) {
+      this.log(`⚠ #1065 sandbox cache-bypass Cache Rule NOT applied (${e.message}) — add zone "Cache Rules" (Account Rulesets) scope to CLOUDFLARE_API_TOKEN or add it once in the CF dashboard`);
+    }
+    return { tunnelId, token, hostname, previewHostname: previewHost, created };
+  }
+
+  // Tear down the per-builder tunnel + its DNS route. Best-effort: each leg is
+  // independent so a missing tunnel still cleans the DNS and vice versa. Returns a
+  // summary the caller can log. Never throws (so deprovision always completes).
+  async teardownNamedTunnel({ login, zone, terminalZone }) {
+    const out = { tunnelDeleted: false, dnsDeleted: false, previewDnsDeleted: false, errors: [] };
+    const name = tunnelName(login);
+    const hostname = terminalHostname(login, terminalZone);
+    const previewHost = previewHostname(login, terminalZone);
+    try {
+      const zoneId = await this.getZoneId(zone);
+      const res = await this.deleteDnsRoute({ zoneId, name: hostname });
+      out.dnsDeleted = !(res && res.missing);
+      // The ADR 0044 preview CNAME shares the tunnel; drop it too (best-effort,
+      // independent leg so a missing record never blocks teardown).
+      try {
+        const pres = await this.deleteDnsRoute({ zoneId, name: previewHost });
+        out.previewDnsDeleted = !(pres && pres.missing);
+      } catch (e) { out.errors.push(`preview-dns: ${e.message}`); }
+    } catch (e) { out.errors.push(`dns: ${e.message}`); }
+    try {
+      const tunnel = await this.findTunnelByName(name);
+      if (tunnel && tunnel.id) {
+        await this.cleanupConnections(tunnel.id).catch(() => {});
+        await this.deleteTunnel(tunnel.id);
+        out.tunnelDeleted = true;
+      }
+    } catch (e) { out.errors.push(`tunnel: ${e.message}`); }
+    return out;
+  }
+}
+
+module.exports = {
+  CfTunnelApi, CfApiError, CF_API_BASE, CFARGO_SUFFIX, TTYD_SERVICE, GAME_SERVICE,
+  tunnelName, terminalHostname, previewHostname,
+  // #1065: the sandbox edge cache-bypass rule constants, exported for the test.
+  CACHE_BYPASS_PHASE, CACHE_BYPASS_RULE_DESC, CACHE_BYPASS_EXPRESSION,
+};