@bongos/core 1.17.0

package/scripts/gds/box.js

@@ -0,0 +1,1258 @@
+#!/usr/bin/env node
+// scripts/gds/box.js — per-builder cloud dev box lifecycle CLI (ADR 0031 §2/§5, #598).
+//
+// The control-plane entrypoint for the box lifecycle. Like provision-staging.sh,
+// it is meant to RUN ON A TRUSTED CONTROL PLANE (the prod droplet, or an
+// operator's machine) — NOT inside a builder box. A builder box provisioning
+// boxes would be a privilege-escalation; the builder firewall doesn't even
+// allow-list the DO API. The rank gate is enforced here against the builder's
+// LIVE DB rank (the same value requireRank reads), so it is a real ADR-0016
+// server-side check, not local prose.
+//
+// Subcommands:
+//   provision <builder>   create + boot a box for a builder (rank-gated)
+//   park      <builder>   snapshot + destroy the droplet (stop compute billing)
+//   wake      <builder>   recreate the droplet from its snapshot
+//   deprovision <builder> destroy droplet AND snapshot (full reclaim)
+//   sweep-idle            deprovision every active box idle > BOX_IDLE_MINUTES (#804)
+//   sweep-dormant         deprovision every box parked > BOX_DORMANT_DAYS (pings builder)
+//   status                print the box roster + estimated cost
+//
+// <builder> is a GitHub login or a numeric builder id.
+//
+// SAFETY: dry-run is the DEFAULT. Nothing touches DigitalOcean or writes the DB
+// unless you pass --apply. Run any command once without --apply to see the plan,
+// exactly like `pulse.js --release-stale --dry-run`.
+//
+//   node scripts/gds/box.js sweep-idle            # plan only
+//   node scripts/gds/box.js sweep-idle --apply     # actually park idle boxes
+//
+// Config (env): DO_API_TOKEN (live only), BOX_PROVISION_MIN_RANK (default xenos),
+//   BOX_REGION (nyc3), BOX_SIZE (s-2vcpu-4gb), BOX_BASE_IMAGE (ubuntu-24-04-x64),
+//   BOX_IDLE_MINUTES (10), BOX_DORMANT_DAYS (14), BOX_SSH_KEY_IDS (comma list),
+//   BOX_DNS_HOOK (optional command, gets BOX_HOSTNAME/BOX_IP in env), BOX_TAG.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const zlib = require('node:zlib');
+const { execFileSync } = require('node:child_process');
+
+// DigitalOcean hard-caps droplet user-data (cloud-init) at 64 KiB. The rendered
+// cloud-init base64-inlines several infra scripts, so it sits close to the cap;
+// #903 (after #898 tipped it over) gzips the biggest one and adds a fail-fast
+// guard. Keep a little headroom under the true 65536 so a stray key/byte is safe.
+const MAX_USERDATA_BYTES = 64 * 1024;
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+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),
+  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',
+  dnsZone: process.env.BOX_DNS_ZONE || 'dev.amazonprimea.com',
+};
+
+// 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, scope added) + the account id, every
+// provision creates a stable term-<login>.dev.amazonprimea.com 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 DNS record lives in (registrable apex), e.g.
+  // amazonprimea.com — term-<login>.dev.amazonprimea.com is a record WITHIN it,
+  // matching box-dns-cloudflare.sh. Distinct from terminalZone (the host suffix).
+  zone: process.env.CLOUDFLARE_ZONE || 'amazonprimea.com',
+  // The host suffix the terminal hostname is built on (term-<login>.<terminalZone>).
+  // DEFAULTS TO THE APEX, NOT dev.* — the terminal rides a PROXIED Cloudflare
+  // tunnel (HTTPS at the edge), and free Universal SSL covers `amazonprimea.com` +
+  // `*.amazonprimea.com` (ONE label) but NOT `term-x.dev.amazonprimea.com` (TWO
+  // labels) → a 2-level host fails TLS at the edge (verified live, #771). One
+  // level (term-<login>.amazonprimea.com) is covered with no paid cert. An
+  // operator with an Advanced Certificate for *.dev.amazonprimea.com can override
+  // via BOX_TERMINAL_ZONE. (The SSH A-record path, box-dns-cloudflare.sh, stays on
+  // dev.* — it is proxied=false / direct-IP, so it needs no edge cert.)
+  terminalZone: process.env.BOX_TERMINAL_ZONE || 'amazonprimea.com',
+};
+
+// 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 namedTunnelEnabled() { return CF.enabled; }
+function namedTunnelConfigured() { return CF.enabled && CF.apiToken && CF.accountId; }
+
+function makeCf(apply) {
+  const { CfTunnelApi } = loadDeps();
+  return new CfTunnelApi({
+    dryRun: !apply,
+    token: CF.apiToken,
+    accountId: CF.accountId,
+    log: (m) => console.log('  ' + m),
+  });
+}
+
+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
+  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  // eslint-disable-next-line global-require
+  const boxes = require(path.join(REPO_ROOT, 'modules/dev-box/boxes'));
+  // eslint-disable-next-line global-require
+  const boxAccess = require(path.join(REPO_ROOT, 'modules/dev-box/box-access'));
+  // eslint-disable-next-line global-require
+  const boxOnboard = require(path.join(REPO_ROOT, 'modules/dev-box/box-onboard'));
+  // eslint-disable-next-line global-require
+  const { DoApi } = require(path.join(REPO_ROOT, 'scripts/gds/do-api'));
+  // eslint-disable-next-line global-require
+  const { CfTunnelApi } = require(path.join(REPO_ROOT, 'scripts/gds/cf-tunnel'));
+  _deps = { pool, boxes, boxAccess, boxOnboard, DoApi, CfTunnelApi };
+  return _deps;
+}
+
+function makeDo(apply) {
+  const { DoApi } = loadDeps();
+  return new DoApi({
+    dryRun: !apply,
+    token: process.env.DO_API_TOKEN || null,
+    log: (m) => console.log('  ' + m),
+  });
+}
+
+// A LIVE read-only DO client for enumerating droplets in the drift reconcile —
+// listing is non-mutating, so it runs for real even in dry-run planning (only the
+// DELETEs are gated by --apply, via the separate makeDo(apply) client). Returns
+// null when DO_API_TOKEN is unset (this is a control-plane command; the token
+// always lives on the prod box) so the caller can fail with a clear message
+// instead of the constructor's throw.
+function makeDoRead() {
+  const token = process.env.DO_API_TOKEN || null;
+  if (!token) return null;
+  const { DoApi } = loadDeps();
+  return new DoApi({ dryRun: false, token, log: (m) => console.log('  ' + m) });
+}
+
+// Best-effort outbound ping to the team Discord (mirrors ship.js's broadcast).
+// OUTBOUND messaging lives in scripts/discord/ as of ADR 0032/#607 — scripts/chat/
+// is inbound-only now, so this must NOT route through chat/post.js (it would fail
+// silently and the builder would never learn their box was reclaimed). Never throws.
+function postReclaimPing(text) {
+  try {
+    execFileSync('node', ['scripts/discord/post.js', text], { cwd: REPO_ROOT, stdio: 'pipe' });
+    return { ok: true };
+  } catch (e) {
+    return { ok: false, error: e && e.message ? e.message : String(e) };
+  }
+}
+
+// Resolve a builder by login or numeric id. Returns the full row or null.
+async function resolveBuilder(pool, ref) {
+  const isId = /^\d+$/.test(String(ref));
+  const { rows } = await pool.query(
+    isId
+      ? `SELECT id, github_login, display_name, rank, status FROM builders WHERE id = $1`
+      : `SELECT id, github_login, display_name, rank, status FROM builders WHERE lower(github_login) = lower($1)`,
+    [ref]
+  );
+  return rows[0] || null;
+}
+
+// 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}`; }
+function hostnameFor(login) { return `box-${login}.${CONFIG.dnsZone}`; }
+
+// Run the optional DNS hook so the per-builder hostname tracks the new IP. When
+// no hook is configured, just print the reminder — the stable-hostname CUTOVER
+// is #599's (Desktop managed-settings); #598 only records IP + hostname + offers
+// the hook so an operator can wire DO/Cloudflare DNS without editing this file.
+// Returns { ok, error?, skipped? }. task 1180: callers MUST act on ok:false
+// (record a box_events row + flag the box) instead of silently continuing — the
+// swallow that left @kingaonline's A record pinned at a dead IP while provision
+// reported success. The hook itself now retries transient Cloudflare blips
+// (infra/box-dns-cloudflare.sh), so ok:false here is a real, exhausted failure.
+// `hook` is injectable so the contract can be unit-tested with a fake (#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 on teardown so it couldn't
+// dangle at a recycled DO IP — but delete-then-recreate across a reap→rebuild
+// left a window where the name returned NXDOMAIN, which resolvers negative-cache
+// for the zone's SOA neg-TTL (~30 min on the Cloudflare amazonprimea.com zone,
+// not builder-editable). A client that queried during that window (e.g. an open
+// Claude Desktop) then kept getting ENOTFOUND long after the box was back and the
+// record recreated. REPOINTING to a non-routable sentinel instead keeps the name
+// always-resolving (no NXDOMAIN → nothing to negative-cache) while preserving
+// 1180's guarantee that a torn-down box's name can never dial a recycled
+// stranger's IP. The next provision/wake PUTs the record straight to the live IP
+// — a clean in-place repoint at the 60s record TTL, no gap. Best-effort (like the
+// prior delete): a failure just leaves the old IP, which the next provision
+// repoints anyway. Reuses the UPSERT path of runDnsHook; `hook` is injectable for
+// tests. Returns { 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 = '' } = {}) {
+  const p = path.join(REPO_ROOT, 'infra', 'builder-box-cloud-init.yaml');
+  // 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/. Warn loudly (not
+  // throw) if a file is unreadable so a half-wired box surfaces, not boots silent.
+  const fileGzB64 = (name) => {
+    try {
+      return zlib.gzipSync(fs.readFileSync(path.join(REPO_ROOT, 'infra', name))).toString('base64');
+    } catch (e) {
+      console.error(`⚠ ${name} not readable (${e.message}) — the box will boot WITHOUT it; fix infra/${name} before provisioning`);
+      return '';
+    }
+  };
+  try {
+    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/.
+    return 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'));
+  } catch { return null; }
+}
+
+// ---- provision -------------------------------------------------------------
+
+async function cmdProvision(pool, boxes, boxOnboard, ref, { apply }) {
+  const builder = await resolveBuilder(pool, ref);
+  if (!builder) return fail(`no builder matches "${ref}"`);
+  if (builder.status && builder.status !== 'active') {
+    return fail(`builder @${builder.github_login} is ${builder.status}, not active — no box`);
+  }
+
+  // Rank gate (ADR 0016 trust boundary: checked against the live DB rank).
+  try {
+    boxes.assertProvisionAllowed({ rank: builder.rank, floor: CONFIG.floor });
+  } catch (e) {
+    return fail(`${e.message}`);
+  }
+
+  // Dry-run must touch nothing (#1034): READ the row instead of ensuring it, so a
+  // bare `provision` (no --apply) cannot write a placeholder builder_boxes row. A
+  // missing row is semantically 'none' — and 'none' is a valid provision source —
+  // so map null→'none' for the gate (NOT the `!box || …` short-circuit the
+  // park/wake paths use: those forbid 'none', but provision allows it). The row is
+  // materialized under --apply below, mirroring wake/park/deprovision (all read via
+  // getBoxByBuilderId).
+  let box = await boxes.getBoxByBuilderId(pool, builder.id);
+  const boxState = box ? box.state : 'none';
+  if (!boxes.canTransition('provision', boxState)) {
+    return fail(`box for @${builder.github_login} is '${boxState}' — provision only from none/destroyed/error (try wake?)`);
+  }
+
+  const scope = boxes.boxScopeForRank(builder.rank);
+  const name = dropletName(builder.github_login);
+  const hostname = hostnameFor(builder.github_login);
+
+  // Bake the builder's registered SSH keys (#685) into the cloud-init so the
+  // FIRST login works before the box has a GDS token. No keys yet → an empty
+  // managed block (the box-authorized-keys-fetch cron fills it in once the
+  // builder authenticates; onboard warns about this case upstream).
+  const sshKeys = await boxOnboard.listSshKeys(pool, builder.id);
+  const authorizedKeysBlock = boxOnboard.wrapManagedBlock(sshKeys);
+
+  console.log(`provision box for @${builder.github_login} (${builder.rank} → scope=${scope})`);
+  console.log(`  region=${CONFIG.region} size=${CONFIG.size} image=${CONFIG.baseImage} host=${hostname}`);
+  console.log(`  baked SSH keys: ${sshKeys.length}${sshKeys.length === 0 ? ' (⚠ builder cannot SSH in until a key is registered — see `box.js onboard`)' : ''}`);
+
+  // Named-tunnel automation (#771, ADR 0038 Part B). OPT-IN: off → the box uses
+  // the tokenless quick tunnel (#760 default) and box.env is left empty. On but
+  // misconfigured → fail loud now (an operator who turned it on meant it).
+  if (namedTunnelEnabled() && !namedTunnelConfigured()) {
+    return fail('BOX_NAMED_TUNNEL is on but CLOUDFLARE_API_TOKEN and/or CLOUDFLARE_ACCOUNT_ID are not set — supply both (token needs Tunnel + DNS scope) or unset BOX_NAMED_TUNNEL for the quick-tunnel default');
+  }
+  const termHost = namedTunnelEnabled() ? `term-${builder.github_login}.${CF.terminalZone}` : null;
+  if (namedTunnelEnabled()) {
+    console.log(`  named tunnel: ${termHost} (Cloudflare zone ${CF.zone})`);
+  } else {
+    console.log('  browser terminal: quick tunnel (tokenless trycloudflare.com — set BOX_NAMED_TUNNEL=1 for a stable hostname)');
+  }
+
+  if (!apply) {
+    console.log('  [dry-run] would create droplet + mark active. Re-run with --apply.');
+    if (namedTunnelEnabled()) await makeCf(false).ensureNamedTunnel({ login: builder.github_login, zone: CF.zone, terminalZone: CF.terminalZone });
+    return { ok: true, dryRun: true };
+  }
+
+  // --apply only: NOW materialize the box row (the dry-run path above left the DB
+  // untouched, #1034). ensureBoxRow is idempotent — returns the existing row or
+  // creates a fresh state='none' one — so box.id / box.provisioned_at below are
+  // always real. Identical to the pre-#1034 --apply behavior; nothing between the
+  // gate above and here reads or writes the box row.
+  box = await boxes.ensureBoxRow(pool, builder.id);
+
+  // Create (or reuse) the named tunnel BEFORE the droplet so its connector token
+  // bakes into the cloud-init box.env. A failure here aborts provision — better
+  // no box than a box that boots without its promised stable terminal.
+  // #774: on the named-tunnel path the control plane knows EVERYTHING the browser
+  // on-ramp needs at provision time — the stable hostname (here) + a password (we
+  // generate it). So we bake the password into box.env (the box serves ttyd with
+  // it) and, once the box is active, RECORD {url, password} into the GDS ourselves
+  // (setTerminalAccess) — the builder reads them from the hall with no token ever
+  // placed on the box and no box-side reporter (that path was the quick-tunnel
+  // fallback and the source of the #771/#774 chicken-and-egg). ADR 0016 holds: no
+  // builder/infra credential is funneled into the box.
+  let boxEnv = '';
+  let terminalHostname = null;
+  let terminalCredential = null;
+  if (namedTunnelEnabled()) {
+    try {
+      const { token, hostname: th, previewHostname: ph } = await makeCf(true).ensureNamedTunnel({
+        login: builder.github_login, zone: CF.zone, terminalZone: CF.terminalZone,
+      });
+      terminalHostname = th;
+      terminalCredential = crypto.randomBytes(24).toString('hex');
+      // ADR 0044: ensureNamedTunnel also created the sandbox-<login> ingress route
+      // + DNS for the live game preview. Bake its hostname so the box's
+      // box-preview command can show the builder their URL (no DB row needed — the
+      // host is deterministic; box-game-preview.service serves :3000 behind it).
+      boxEnv = `# /etc/otb/box.env — baked by box.js provision (#771/#774, ADR 0038 named tunnel)\nBOX_TUNNEL_TOKEN=${token}\nBOX_TERMINAL_HOSTNAME=${th}\nBOX_TERMINAL_CREDENTIAL=${terminalCredential}\nBOX_PREVIEW_HOSTNAME=${ph}\n`;
+      console.log(`  ✓ named tunnel ready — ${th}`);
+      console.log(`  ✓ live game preview — https://${ph} (ADR 0044)`);
+    } catch (e) {
+      await boxes.setBoxState(pool, builder.id, 'error', { error_note: `named tunnel: ${e.message}` });
+      return fail(`named tunnel setup failed: ${e.message}`);
+    }
+  }
+
+  // Bootstrap the builder's GDS session onto the box (#818). box-source-fetch
+  // (#600) authenticates as the BUILDER to pull the rank-scoped repo; without a
+  // session at ~/.config/otb/gds-session.json it no-ops forever, so the repo
+  // never clones, the devcontainer never comes up, and /builder-* skills are
+  // absent. The session normally comes from /builder-setup — which lives in the
+  // un-cloned repo (the chicken-and-egg). So we mint a session here and bake it
+  // into cloud-init, exactly like the SSH keys / tunnel token / terminal credential.
+  //
+  // SECURITY (#919, SR#2): this baked session is source='box' — a SCOPED, 24h
+  // refresh-on-use credential. The token lives ON the box (readable by any on-box
+  // process + the metadata endpoint), which is OUTSIDE the ADR 0016 trust boundary,
+  // so it must NOT carry the builder's full authority. auth.requireBuilder denies a
+  // 'box' session on every route except the 4 the on-box crons need (source-access,
+  // authorized-keys, heartbeat, terminal — gated by auth.allowBoxScope). The first
+  // source-fetch clones on boot; the repo persists in the snapshot. To do real work
+  // FROM the box (claim/ship) the builder runs /builder-reauth (device flow), minting
+  // a normal cli/web session — never auto-baked. user_agent='box-provision' is the
+  // marker migration 090 keys on to retroactively scope already-baked tokens.
+  const gdsDb = require(path.join(REPO_ROOT, 'src/bongos/db'));
+  const sessionToken = crypto.randomBytes(32).toString('hex');
+  await gdsDb.createSession({
+    builderId: builder.id, token: sessionToken, source: 'box', userAgent: 'box-provision',
+  });
+  const gdsSession = JSON.stringify({
+    token: sessionToken,
+    builder: { id: builder.id, github_login: builder.github_login, rank: builder.rank },
+    api_base: process.env.GDS_PUBLIC_ORIGIN || 'https://amazonprimea.com',
+  }, null, 2);
+
+  const doApi = makeDo(apply);
+  // Render + size-check the cloud-init BEFORE touching DO (#903). DO rejects
+  // user-data over 64 KiB with an opaque error; fail fast with an actionable one
+  // so an over-budget cloud-init is caught here, not as a cryptic API 4xx.
+  const userData = readCloudInit({ authorizedKeysBlock, boxEnv, gdsSession });
+  const userDataBytes = userData ? Buffer.byteLength(userData, 'utf8') : 0;
+  if (userDataBytes > MAX_USERDATA_BYTES) {
+    await boxes.setBoxState(pool, builder.id, 'error', {
+      error_note: `cloud-init ${userDataBytes}B > ${MAX_USERDATA_BYTES}B`,
+    });
+    return fail(`cloud-init user-data is ${userDataBytes}B, over DigitalOcean's ${MAX_USERDATA_BYTES}B limit — trim infra/box-source-fetch.sh or gzip more of the inlined files (infra/builder-box-cloud-init.yaml)`);
+  }
+  await boxes.setBoxState(pool, builder.id, 'provisioning', {
+    scope, provisioned_rank: builder.rank, region: CONFIG.region, size_slug: CONFIG.size,
+    droplet_name: name, hostname, error_note: null,
+  });
+  try {
+    const { droplet } = await doApi.createDroplet({
+      name, region: CONFIG.region, size: CONFIG.size, image: CONFIG.baseImage,
+      userData, tags: [CONFIG.tag, `builder:${builder.github_login}`],
+      sshKeys: CONFIG.sshKeyIds.length ? CONFIG.sshKeyIds : undefined,
+    });
+    const { ip } = await doApi.settleDroplet(droplet.id);
+    const now = new Date();
+    await boxes.setBoxState(pool, builder.id, 'active', {
+      droplet_id: String(droplet.id), ip, snapshot_id: null,
+      provisioned_at: box.provisioned_at || now, active_since: now, last_activity_at: now,
+    });
+    await boxes.recordEvent(pool, {
+      boxId: box.id, builderId: builder.id, event: 'provision',
+      detail: `droplet ${droplet.id} ${ip || ''} ${CONFIG.size}`, actor: actorTag(),
+    });
+    // #602: log a spin-up event in the per-builder cost ledger.
+    await boxes.recordSpinupCost(pool, { box, kind: 'provision', atMs: now.getTime(), actor: actorTag() });
+    // #774: record the browser-terminal access NOW (named-tunnel path) so the hall
+    // serves it immediately — no waiting on the box to report, no token on the box.
+    // The box brings ttyd up at first boot with this same password (baked above).
+    if (terminalHostname && terminalCredential) {
+      try {
+        await boxes.setTerminalAccess(pool, builder.id, {
+          url: `https://${terminalHostname}`, credential: terminalCredential,
+        });
+        console.log(`  ✓ terminal access recorded — https://${terminalHostname}`);
+      } catch (e) {
+        console.log(`  ⚠ could not record terminal access (non-fatal): ${e.message}`);
+      }
+    }
+    const dns = runDnsHook(hostname, ip);
+    if (!dns.ok) {
+      // task 1180: a stale DNS must NOT pass as a clean provision. Record it so the
+      // box is queryable as DNS-stale (the box still provisions — failure-open).
+      await boxes.recordEvent(pool, {
+        boxId: box.id, builderId: builder.id, event: 'error',
+        detail: `dns_repoint_failed: ${dns.error || 'DNS hook failed'} (${hostname} -> ${ip})`,
+        actor: actorTag(),
+      });
+    }
+    console.log(`  ✓ active — droplet ${droplet.id}${ip ? ` @ ${ip}` : ''}${dns.ok ? '' : '  ⚠ DNS STALE — Desktop SSH will fail until repointed (browser terminal unaffected)'}`);
+    return { ok: true };
+  } catch (e) {
+    await boxes.setBoxState(pool, builder.id, 'error', { error_note: e.message });
+    await boxes.recordEvent(pool, { boxId: box.id, builderId: builder.id, event: 'error', detail: e.message, actor: actorTag() });
+    return fail(`provision failed: ${e.message}`);
+  }
+}
+
+// ---- onboard (the operator one-shot: provision + welcome packet) -----------
+
+// `box.js onboard <login>` is the operator's single command for #685: it
+// provisions the box (baking the builder's already-registered SSH keys) and then
+// prints a copy-paste "welcome packet" to forward to the builder. The canonical
+// order is: builder runs box-connect (registers key + installs managed-settings)
+// → operator runs onboard → builder restarts Desktop and connects. Because the
+// box can't fetch its own authorized_keys until the builder has a token ON the
+// box (chicken-and-egg), onboard REQUIRES at least one registered key by default;
+// --allow-no-keys overrides for an operator who knows they'll re-provision later.
+function gdsBase() {
+  return (process.env.GDS_API_BASE || 'https://amazonprimea.com').replace(/\/+$/, '');
+}
+
+function printWelcomePacket(login, scope) {
+  const base = gdsBase();
+  const host = hostnameFor(login);
+  console.log('');
+  console.log(`──────── welcome packet for @${login} — forward to the builder ────────`);
+  console.log('');
+  console.log('If you have not already connected this device, run ONE of these on your');
+  console.log('own Mac/Windows (it signs you in, makes + registers your SSH key, and');
+  console.log('installs the Claude Desktop connection file):');
+  console.log('');
+  console.log(`  macOS/Linux:  curl -fsSL ${base}/api/gds/box/connect.sh | bash`);
+  console.log(`  Windows:      irm ${base}/api/gds/box/connect.ps1 | iex`);
+  console.log(`  (guide:       ${base}/api/gds/box/connect )`);
+  console.log('');
+  console.log('Then: restart Claude Desktop → Code → Environment → "Amazonprimea Dev Box".');
+  console.log('');
+  console.log('On a Chromebook / browser-only device (no Claude Desktop)? Skip the above —');
+  console.log('your box serves its own terminal in a browser tab (ADR 0038). Once it is');
+  console.log('active, get the URL + password and open it:');
+  console.log(`  GET ${base}/api/gds/box/terminal   (or run /builder-box)`);
+  console.log('In that terminal, type `claude` to start working.');
+  console.log('');
+  console.log(`Your box:  ${host}  (scope=${scope})`);
+  console.log('Your memory + credits are server-side and follow you to any box (ADR 0024).');
+  console.log('───────────────────────────────────────────────────────────────────────');
+}
+
+async function cmdOnboard(pool, boxes, boxOnboard, ref, { apply, allowNoKeys }) {
+  const builder = await resolveBuilder(pool, ref);
+  if (!builder) return fail(`no builder matches "${ref}"`);
+
+  const keys = await boxOnboard.listSshKeys(pool, builder.id);
+  if (keys.length === 0 && !allowNoKeys) {
+    console.error(`✖ @${builder.github_login} has no registered SSH key yet — the box would have no way in.`);
+    console.error('');
+    console.error('  Ask the builder to connect FIRST (this registers their key), then re-run onboard:');
+    console.error(`    macOS/Linux:  curl -fsSL ${gdsBase()}/api/gds/box/connect.sh | bash`);
+    console.error(`    Windows:      irm ${gdsBase()}/api/gds/box/connect.ps1 | iex`);
+    console.error('');
+    console.error('  (Override with --allow-no-keys to provision a keyless box anyway — you will');
+    console.error('   then have to re-provision once they register a key.)');
+    return fail('no SSH key registered for this builder');
+  }
+
+  console.log(`onboard @${builder.github_login} — provision + welcome packet (${keys.length} SSH key(s) registered)`);
+  const result = await cmdProvision(pool, boxes, boxOnboard, ref, { apply });
+  if (result && result.ok === false) return result;
+
+  const scope = boxes.boxScopeForRank(builder.rank);
+  printWelcomePacket(builder.github_login, scope);
+  if (!apply) console.log('\n[dry-run] no box created — re-run with --apply to provision for real.');
+  return { ok: true, dryRun: !apply };
+}
+
+// ---- park (snapshot + destroy) ---------------------------------------------
+
+async function parkOne(pool, boxes, doApi, box, { actor }) {
+  const now = Date.now();
+  await boxes.setBoxState(pool, box.builder_id, 'parking');
+  // Power off for a clean snapshot, snapshot, wait, then destroy the droplet.
+  await doApi.powerOffDroplet(box.droplet_id).then((r) => r.action && doApi.waitForAction(r.action.id));
+  const snapName = `otb-snap-${box.droplet_name || box.builder_id}-${shortStamp()}`;
+  const snapRes = await doApi.snapshotDroplet(box.droplet_id, snapName);
+  if (snapRes.action) await doApi.waitForAction(snapRes.action.id);
+  // Resolve the new snapshot id from the droplet's snapshot_ids (live mode).
+  let snapshotId = null;
+  if (!doApi.dryRun) {
+    const { droplet } = await doApi.getDroplet(box.droplet_id);
+    const ids = (droplet && droplet.snapshot_ids) || [];
+    snapshotId = ids.length ? String(ids[ids.length - 1]) : null;
+  } else {
+    snapshotId = `dryrun-snap-${box.builder_id}`;
+  }
+  // Accrue the compute cost for this active interval BEFORE we lose active_since.
+  await boxes.recordComputeCost(pool, { box, untilMs: now, actor });
+  await doApi.deleteDroplet(box.droplet_id);
+  await boxes.setBoxState(pool, box.builder_id, 'parked', {
+    snapshot_id: snapshotId, parked_at: new Date(now),
+    droplet_id: null, ip: null, active_since: null,
+  });
+  await boxes.recordEvent(pool, {
+    boxId: box.id, builderId: box.builder_id, event: 'park',
+    detail: `snapshot ${snapshotId}; droplet ${box.droplet_id} destroyed`, actor,
+  });
+}
+
+async function cmdPark(pool, boxes, ref, { apply }) {
+  const builder = await resolveBuilder(pool, ref);
+  if (!builder) return fail(`no builder matches "${ref}"`);
+  const box = await boxes.getBoxByBuilderId(pool, builder.id);
+  if (!box || !boxes.canTransition('park', box.state)) {
+    return fail(`box for @${builder.github_login} is '${box ? box.state : 'none'}' — park only from active`);
+  }
+  console.log(`park box for @${builder.github_login} (droplet ${box.droplet_id})`);
+  if (!apply) { console.log('  [dry-run] would snapshot + destroy droplet. Re-run with --apply.'); return { ok: true, dryRun: true }; }
+  try {
+    await parkOne(pool, boxes, makeDo(apply), box, { actor: actorTag() });
+    console.log('  ✓ parked (snapshot kept; droplet destroyed — compute billing stopped)');
+    return { ok: true };
+  } catch (e) {
+    await boxes.setBoxState(pool, builder.id, 'error', { error_note: e.message });
+    return fail(`park failed: ${e.message}`);
+  }
+}
+
+// ---- wake (recreate from snapshot) -----------------------------------------
+
+async function cmdWake(pool, boxes, ref, { apply }) {
+  const builder = await resolveBuilder(pool, ref);
+  if (!builder) return fail(`no builder matches "${ref}"`);
+  const box = await boxes.getBoxByBuilderId(pool, builder.id);
+  if (!box || !boxes.canTransition('wake', box.state)) {
+    return fail(`box for @${builder.github_login} is '${box ? box.state : 'none'}' — wake only from parked`);
+  }
+  if (!box.snapshot_id) return fail(`parked box for @${builder.github_login} has no snapshot_id — cannot wake (deprovision + re-provision)`);
+  console.log(`wake box for @${builder.github_login} (from snapshot ${box.snapshot_id})`);
+  if (!apply) { console.log('  [dry-run] would recreate droplet from snapshot. Re-run with --apply.'); return { ok: true, dryRun: true }; }
+  const doApi = makeDo(apply);
+  await boxes.setBoxState(pool, builder.id, 'waking');
+  try {
+    const { droplet } = await doApi.createDropletFromSnapshot({
+      name: box.droplet_name || dropletName(builder.github_login),
+      region: box.region, size: box.size_slug, snapshotId: box.snapshot_id,
+      tags: [CONFIG.tag, `builder:${builder.github_login}`],
+      sshKeys: CONFIG.sshKeyIds.length ? CONFIG.sshKeyIds : undefined,
+    });
+    const { ip } = await doApi.settleDroplet(droplet.id);
+    const now = new Date();
+    await boxes.setBoxState(pool, builder.id, 'active', {
+      droplet_id: String(droplet.id), ip, active_since: now, last_activity_at: now, parked_at: null,
+    });
+    await boxes.recordEvent(pool, { boxId: box.id, builderId: builder.id, event: 'wake', detail: `droplet ${droplet.id} ${ip || ''}`, actor: actorTag() });
+    // #602: the box just ended a PARKED interval (snapshot retained) — accrue its
+    // storage cost before active_since restarts compute, then log the wake spin-up.
+    // `box` is the pre-wake row, so it still carries parked_at.
+    await boxes.recordStorageCost(pool, { box, untilMs: now.getTime(), actor: actorTag() });
+    await boxes.recordSpinupCost(pool, { box, kind: 'wake', atMs: now.getTime(), actor: actorTag() });
+    const wakeHost = box.hostname || hostnameFor(builder.github_login);
+    const dns = runDnsHook(wakeHost, ip);
+    if (!dns.ok) {
+      await boxes.recordEvent(pool, {
+        boxId: box.id, builderId: builder.id, event: 'error',
+        detail: `dns_repoint_failed: ${dns.error || 'DNS hook failed'} (${wakeHost} -> ${ip})`,
+        actor: actorTag(),
+      });
+    }
+    console.log(`  ✓ active — droplet ${droplet.id}${ip ? ` @ ${ip}` : ''}${dns.ok ? '' : '  ⚠ DNS STALE — Desktop SSH will fail until repointed (browser terminal unaffected)'}`);
+    return { ok: true };
+  } catch (e) {
+    await boxes.setBoxState(pool, builder.id, 'error', { error_note: e.message });
+    return fail(`wake failed: ${e.message}`);
+  }
+}
+
+// ---- deprovision (destroy droplet + snapshot) ------------------------------
+
+// Idempotent delete with a few retries for transient DigitalOcean blips. A 404
+// means the resource is ALREADY gone — that is success, not failure (the whole
+// point of an idempotent teardown). Returns { ok:true } once the resource is
+// confirmed absent, or { ok:false, error } after the retry budget is spent on a
+// real (non-404) failure. `sleepFn` is injectable so tests drive it instantly.
+async function deleteWithRetry(fn, { tries = 3, sleepMs = 2000, sleepFn } = {}) {
+  const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  let lastErr = null;
+  for (let i = 0; i < tries; i++) {
+    try {
+      await fn();
+      return { ok: true, alreadyGone: false };
+    } catch (e) {
+      if (e && e.status === 404) return { ok: true, alreadyGone: true };
+      lastErr = e;
+      if (i < tries - 1) await sleep(sleepMs);
+    }
+  }
+  return { ok: false, error: lastErr || new Error('delete failed') };
+}
+
+// CONFIRM-BEFORE-DESTROYED (task 1289). The old teardown swallowed a failed
+// droplet delete (`.catch(log)`) and then set state='destroyed' UNCONDITIONALLY,
+// nulling droplet_id — so a transient DO failure left a droplet running + billing
+// + SSH-reachable while the DB claimed it was gone (the zombie). Now the droplet
+// delete is the GATE: it is retried + idempotent, and if it genuinely fails the box
+// is parked at state='error' with its droplet_id PRESERVED (so it's queryable and
+// the drift reconcile can find it) and the function THROWS — the row never reaches
+// 'destroyed' until DO confirms the droplet is gone. Snapshot/tunnel/DNS stay
+// best-effort (a leftover snapshot is cost-only; the box is already gone for the
+// tunnel/DNS), but the snapshot delete is now idempotent too.
+async function deprovisionOne(pool, boxes, doApi, box, { actor, login, sleepFn } = {}) {
+  const now = Date.now();
+  if (box.state === 'active' && box.droplet_id) {
+    await boxes.recordComputeCost(pool, { box, untilMs: now, actor });
+  }
+  // #602: deprovisioning a PARKED box ends a snapshot-storage interval — accrue it
+  // (no-op for an active/never-parked box, where parked_at is null).
+  if (box.parked_at) {
+    await boxes.recordStorageCost(pool, { box, untilMs: now, actor });
+  }
+  if (box.droplet_id) {
+    const r = await deleteWithRetry(() => doApi.deleteDroplet(box.droplet_id), { sleepFn });
+    if (!r.ok) {
+      // Do NOT mark 'destroyed' — that is the bug. Park at 'error' with droplet_id
+      // intact so the row stays truthful (a droplet is still out there) and throw.
+      const msg = (r.error && r.error.message) || 'droplet delete failed';
+      await boxes.setBoxState(pool, box.builder_id, 'error', {
+        error_note: `droplet ${box.droplet_id} delete failed (not destroyed): ${msg}`,
+      });
+      await boxes.recordEvent(pool, {
+        boxId: box.id, builderId: box.builder_id, event: 'error',
+        detail: `deprovision aborted: droplet ${box.droplet_id} delete failed: ${msg}`, actor,
+      });
+      throw r.error || new Error(msg);
+    }
+  }
+  if (box.snapshot_id) {
+    const sr = await deleteWithRetry(() => doApi.deleteSnapshot(box.snapshot_id), { sleepFn });
+    if (!sr.ok) console.log(`  ⚠ snapshot delete (left behind, cost-only): ${(sr.error && sr.error.message) || 'failed'}`);
+  }
+  // Named-tunnel teardown (#771, ADR 0038 Part B). Best-effort — the box is gone
+  // by now, so a leftover tunnel/DNS is only cosmetic, never a blocker. The
+  // droplet was destroyed above, dropping the connector connections, so the
+  // tunnel deletes cleanly. login is the deterministic key (tunnel name + host).
+  const who = login || box.github_login;
+  if (namedTunnelConfigured() && who) {
+    try {
+      const res = await makeCf(!doApi.dryRun).teardownNamedTunnel({ login: who, zone: CF.zone, terminalZone: CF.terminalZone });
+      if (res.tunnelDeleted || res.dnsDeleted) console.log(`  ✓ named tunnel torn down (tunnel=${res.tunnelDeleted} dns=${res.dnsDeleted})`);
+      for (const err of res.errors) console.log(`  ⚠ tunnel teardown ${err}`);
+    } catch (e) { console.log(`  ⚠ named tunnel teardown: ${e.message}`); }
+  }
+  // task 1180 + idea 309: park the per-builder SSH A record at the blackhole
+  // sentinel (don't delete it) after teardown. This still stops the record
+  // dangling at a recycled DO IP (the amplifier behind the stale-DNS outage),
+  // AND it avoids the NXDOMAIN gap that a delete-then-recreate opened on a
+  // reap→rebuild (idea 309): a deleted name negative-caches for the zone neg-TTL
+  // (~30 min), so a client that queried mid-gap kept getting ENOTFOUND long after
+  // the box was back. The name now always resolves (to a non-routable sentinel),
+  // so there's nothing to negative-cache; the next provision/wake repoints it to
+  // the live IP in place. Best-effort/non-fatal, like the tunnel teardown above;
+  // box.hostname was stamped at provision, and the browser terminal rides the
+  // tunnel, not this record.
+  const dnsHost = box.hostname || (who ? hostnameFor(who) : null);
+  if (CONFIG.dnsHook && dnsHost) runDnsHookBlackhole(dnsHost);
+  await boxes.setBoxState(pool, box.builder_id, 'destroyed', {
+    destroyed_at: new Date(now), droplet_id: null, ip: null, snapshot_id: null,
+    active_since: null, parked_at: null, claude_active: false,
+    // idea 310: a rebuilt box mints fresh SSH host keys, but the GDS row kept the
+    // OLD keys until the new box re-reported (~10 min). In that window GET /box/me
+    // served a stale identity and the desktop app pinned the WRONG key — the
+    // "Host denied (verification failed)" that locked builders out. Clear them on
+    // teardown; the next box re-reports via POST /box/host-keys on provision. (A
+    // park→wake keeps its keys via the snapshot, so this only fires on full destroy.)
+    host_keys: null, host_keys_at: null,
+  });
+  // Post-'destroyed' audit-log write. The teardown is already COMMITTED above
+  // (droplet confirmed gone, row at 'destroyed', ids nulled), so this event is
+  // best-effort like the snapshot/tunnel/DNS steps — it MUST NOT throw. A failed
+  // audit write here used to propagate to the caller's catch (the sweep /
+  // deprovision / reconcile loops), which then flipped the just-committed
+  // 'destroyed' back to 'error' with a null droplet_id — the false-error that
+  // stranded builder 95 on 2026-07-04 (task 2034). Swallow + log instead; the
+  // markErrorUnlessDestroyed guard below is the second line of defence for any
+  // OTHER post-commit write (e.g. the reconcile path's recordSourceEvent).
+  try {
+    await boxes.recordEvent(pool, {
+      boxId: box.id, builderId: box.builder_id, event: 'deprovision',
+      detail: `droplet ${box.droplet_id || '-'} + snapshot ${box.snapshot_id || '-'} destroyed`, actor,
+    });
+  } catch (e) {
+    console.log(`  ⚠ teardown complete (state=destroyed) but the deprovision audit event failed to record: ${e.message}`);
+  }
+}
+
+// A teardown that has already COMMITTED state='destroyed' must never be flipped
+// back to 'error' by a LATER failure. deprovisionOne commits 'destroyed' and then
+// runs best-effort follow-ups (its own recordEvent — now wrapped — and, on the
+// reconcile path, recordSourceEvent); if one of those throws it lands in the
+// caller's catch, which would otherwise overwrite the good 'destroyed' with
+// 'error' and a null droplet_id (the false-error that stranded builder 95,
+// 2026-07-04 — task 2034). This guard re-reads the row and only parks at 'error'
+// when the box did NOT reach 'destroyed'. Never throws (it runs inside a catch).
+async function markErrorUnlessDestroyed(pool, boxes, builderId, errNote) {
+  try {
+    const current = await boxes.getBoxByBuilderId(pool, builderId);
+    if (current && current.state === 'destroyed') {
+      console.log(`  ⚠ teardown completed (state=destroyed); ignoring a post-teardown failure: ${errNote}`);
+      return;
+    }
+    await boxes.setBoxState(pool, builderId, 'error', { error_note: errNote });
+  } catch (e) {
+    console.log(`  ⚠ could not record error state for builder ${builderId}: ${e.message}`);
+  }
+}
+
+async function cmdDeprovision(pool, boxes, ref, { apply }) {
+  const builder = await resolveBuilder(pool, ref);
+  if (!builder) return fail(`no builder matches "${ref}"`);
+  const box = await boxes.getBoxByBuilderId(pool, builder.id);
+  if (!box || !boxes.canTransition('deprovision', box.state)) {
+    return fail(`box for @${builder.github_login} is '${box ? box.state : 'none'}' — nothing to deprovision`);
+  }
+  console.log(`deprovision box for @${builder.github_login} (droplet ${box.droplet_id || '-'}, snapshot ${box.snapshot_id || '-'})`);
+  if (!apply) { console.log('  [dry-run] would destroy droplet AND snapshot. Re-run with --apply.'); return { ok: true, dryRun: true }; }
+  try {
+    await deprovisionOne(pool, boxes, makeDo(apply), box, { actor: actorTag(), login: builder.github_login });
+    console.log('  ✓ destroyed (droplet + snapshot gone; all box cost stopped)');
+    return { ok: true };
+  } catch (e) {
+    await markErrorUnlessDestroyed(pool, boxes, builder.id, e.message);
+    return fail(`deprovision failed: ${e.message}`);
+  }
+}
+
+// ---- sweep-idle ------------------------------------------------------------
+// Idle boxes are deprovisioned directly (no park step). Park is removed from the
+// automated lifecycle — it added snapshot storage cost (~$0.30/mo) with no
+// benefit given boxes are ephemeral by design (builders provision fresh each session).
+// Park remains available as a manual CLI command for Archon use.
+
+async function cmdSweepIdle(pool, boxes, { apply }) {
+  const rows = await boxes.listBoxes(pool, { state: 'active' });
+  const idle = boxes.selectIdleBoxes(rows, { idleMinutes: CONFIG.idleMinutes, nowMs: Date.now() });
+  console.log(`idle sweep (threshold=${CONFIG.idleMinutes}m${apply ? '' : ', dry-run'}): ${idle.length} of ${rows.length} active box(es) idle`);
+  if (idle.length === 0) { console.log('  nothing idle — exit clean'); return { deprovisioned: 0 }; }
+  const doApi = apply ? makeDo(apply) : null;
+  let deprovisioned = 0, errors = 0;
+  for (const box of idle) {
+    const mins = Math.round((Date.now() - (boxes.effectiveActivityMs(box) || Date.now())) / 60000);
+    if (!apply) { console.log(`  would deprovision @${box.github_login}'s box (idle ${mins}m, droplet ${box.droplet_id})`); continue; }
+    try {
+      await deprovisionOne(pool, boxes, doApi, box, { actor: 'sweep:idle', login: box.github_login });
+      deprovisioned++;
+      console.log(`  ✓ deprovisioned @${box.github_login} (idle ${mins}m)`);
+    } catch (e) {
+      errors++;
+      await markErrorUnlessDestroyed(pool, boxes, box.builder_id, e.message);
+      console.log(`  ✖ @${box.github_login}: ${e.message}`);
+    }
+  }
+  console.log(`done — deprovisioned=${deprovisioned} errors=${errors} dry-run=${!apply}`);
+  return { deprovisioned, errors };
+}
+
+// ---- sweep-dormant ---------------------------------------------------------
+
+async function cmdSweepDormant(pool, boxes, { apply }) {
+  const rows = await boxes.listBoxes(pool, { state: 'parked' });
+  const dormant = boxes.selectDormantBoxes(rows, { dormantDays: CONFIG.dormantDays, nowMs: Date.now() });
+  console.log(`dormant sweep (threshold=${CONFIG.dormantDays}d${apply ? '' : ', dry-run'}): ${dormant.length} of ${rows.length} parked box(es) dormant`);
+  if (dormant.length === 0) { console.log('  nothing dormant — exit clean'); return { reclaimed: 0 }; }
+  const doApi = apply ? makeDo(apply) : null;
+  let reclaimed = 0, errors = 0, pingFailed = 0;
+  for (const box of dormant) {
+    const days = Math.round((Date.now() - Date.parse(box.parked_at)) / 86400000);
+    if (!apply) { console.log(`  would reclaim @${box.github_login}'s box (parked ${days}d, snapshot ${box.snapshot_id})`); continue; }
+    try {
+      await deprovisionOne(pool, boxes, doApi, box, { actor: 'sweep:dormant' });
+      reclaimed++;
+      const ping = postReclaimPing(`@${box.github_login} — your dev box was idle for ${days} days and has been reclaimed to save cost. Ask an Archon to re-provision when you're back; your memory is server-side and unaffected.`);
+      if (!ping.ok) pingFailed++;
+      console.log(`  ✓ reclaimed @${box.github_login} (parked ${days}d)${ping.ok ? '' : ' [chat ping failed]'}`);
+    } catch (e) { errors++; await markErrorUnlessDestroyed(pool, boxes, box.builder_id, e.message); console.log(`  ✖ @${box.github_login}: ${e.message}`); }
+  }
+  console.log(`done — reclaimed=${reclaimed} ping-failed=${pingFailed} errors=${errors} dry-run=${!apply}`);
+  return { reclaimed, errors, pingFailed };
+}
+
+// ---- reconcile (source-access clawback) ------------------------------------
+
+// The control-plane half of rank-gated source access (ADR 0031 §6, #600). The
+// CREDENTIAL layer is already gated live on every GET /box/source-access fetch, so
+// revocation is instant there; this is the slower droplet-level reconcile that
+// brings each box into line with its builder's LIVE rank+status:
+//   - below the floor / builder inactive  → deprovision (no box, no source)
+//   - 'full' box whose builder fell below Metic+ → deprovision (can't un-see the
+//        crown jewels; a fresh starter box can be provisioned)
+//   - 'starter' box whose builder graduated to Metic+ → rescope to 'full' (the box
+//        re-clones the full surface on its next source-access refresh)
+// Run it on a schedule (alongside the sweeps) for hands-off offboarding. DRY-RUN
+// DEFAULT — pass --apply to actually deprovision / rescope.
+async function cmdReconcile(pool, boxes, boxAccess, { apply }) {
+  const rows = await boxAccess.listBoxesForReconcile(pool);
+  const actions = rows
+    .map((box) => ({
+      box,
+      decision: boxAccess.reconcileSourceAccess({
+        boxScope: box.scope, boxState: box.state,
+        rank: box.rank, status: box.status, floor: CONFIG.floor,
+      }),
+    }))
+    .filter((x) => x.decision.action !== 'none');
+
+  console.log(`source-access reconcile (floor=${CONFIG.floor}${apply ? '' : ', dry-run'}): ${actions.length} of ${rows.length} box(es) need action`);
+  if (actions.length === 0) { console.log('  all boxes in sync — exit clean'); return { deprovisioned: 0, rescoped: 0 }; }
+
+  const doApi = apply ? makeDo(apply) : null;
+  let deprovisioned = 0, rescoped = 0, errors = 0;
+  for (const { box, decision } of actions) {
+    if (!apply) {
+      console.log(`  would ${decision.action} @${box.github_login}'s box — ${decision.reason} (scope=${box.scope}, rank=${box.rank}, status=${box.status})`);
+      continue;
+    }
+    try {
+      if (decision.action === 'deprovision') {
+        await deprovisionOne(pool, boxes, doApi, box, { actor: 'reconcile:clawback' });
+        await boxAccess.recordSourceEvent(pool, {
+          box, builderId: box.builder_id, event: 'source_revoke',
+          detail: `deprovisioned: ${decision.reason} (rank=${box.rank}, status=${box.status})`, actor: 'reconcile',
+        });
+        deprovisioned++;
+        console.log(`  ✓ deprovisioned @${box.github_login} — ${decision.reason}`);
+      } else if (decision.action === 'rescope') {
+        await boxes.setBoxState(pool, box.builder_id, box.state, {
+          scope: decision.newScope, provisioned_rank: box.rank,
+        });
+        await boxAccess.recordSourceEvent(pool, {
+          box, builderId: box.builder_id, event: 'source_rescope',
+          detail: `${box.scope}→${decision.newScope}: ${decision.reason}`, actor: 'reconcile',
+        });
+        rescoped++;
+        console.log(`  ✓ rescoped @${box.github_login} ${box.scope}→${decision.newScope} (box re-clones on next refresh)`);
+      }
+    } catch (e) {
+      errors++;
+      await markErrorUnlessDestroyed(pool, boxes, box.builder_id, e.message);
+      console.log(`  ✖ @${box.github_login}: ${e.message}`);
+    }
+  }
+  console.log(`done — deprovisioned=${deprovisioned} rescoped=${rescoped} errors=${errors} dry-run=${!apply}`);
+  return { deprovisioned, rescoped, errors };
+}
+
+// ---- reconcile-drift (DO droplet list ⇄ GDS box rows, task 1289) -----------
+
+// Best-effort teardown of a login's edge resources (Cloudflare named tunnel + the
+// per-builder DNS A record), shared by the zombie + ghost reconcile paths so no
+// orphan tunnel/DNS is left behind. Never throws — the droplet (the thing that
+// bills + is SSH-reachable) is the hard part; a leftover tunnel/DNS is cosmetic.
+async function teardownEdgeForLogin(login, { apply }) {
+  if (!login) return;
+  if (namedTunnelConfigured()) {
+    try {
+      const res = await makeCf(apply).teardownNamedTunnel({ login, zone: CF.zone, terminalZone: CF.terminalZone });
+      if (res.tunnelDeleted || res.dnsDeleted) console.log(`    ✓ tunnel torn down (tunnel=${res.tunnelDeleted} dns=${res.dnsDeleted})`);
+      for (const err of res.errors) console.log(`    ⚠ tunnel teardown ${err}`);
+    } catch (e) { console.log(`    ⚠ tunnel teardown: ${e.message}`); }
+  }
+  if (CONFIG.dnsHook && apply) runDnsHookBlackhole(hostnameFor(login));
+}
+
+// The bidirectional drift sweep. Lists the REAL fleet droplets (live read, even in
+// dry-run) and reconciles against the GDS box rows:
+//   - ZOMBIE (droplet exists, no live row claims it) → force-delete droplet + edge.
+//   - GHOST  (live row, its droplet vanished from DO) → mark 'destroyed' + edge.
+// This is the backstop for any teardown that half-failed (now far less likely with
+// confirm-before-destroyed in deprovisionOne) and for out-of-band DO changes.
+// DRY-RUN DEFAULT — pass --apply to actually delete / mark.
+async function cmdReconcileDrift(pool, boxes, { apply }) {
+  const readApi = makeDoRead();
+  if (!readApi) {
+    return fail('reconcile-drift needs DO_API_TOKEN to enumerate droplets — run on the control plane (prod droplet)');
+  }
+  let droplets;
+  try {
+    ({ droplets } = await readApi.listDroplets({ tag: CONFIG.tag }));
+  } catch (e) {
+    return fail(`could not list DigitalOcean droplets: ${e.message}`);
+  }
+  const boxRows = await boxes.listBoxes(pool, {});
+  const { zombies, ghosts, skippedYoung } = boxes.planDropletDrift({
+    droplets: droplets || [], boxRows, nowMs: Date.now(),
+  });
+
+  console.log(`drift reconcile (fleet tag=${CONFIG.tag}${apply ? '' : ', dry-run'}): ${(droplets || []).length} droplet(s) live, ${boxRows.length} box row(s)`);
+  console.log(`  zombies=${zombies.length} ghosts=${ghosts.length} skipped-young=${skippedYoung.length}`);
+  for (const z of skippedYoung) console.log(`  · skip young droplet ${z.dropletId} (${z.name || '?'}) — likely a provision in flight`);
+  if (zombies.length === 0 && ghosts.length === 0) { console.log('  DO ⇄ DB consistent — exit clean'); return { zombies: 0, ghosts: 0 }; }
+
+  const mutateDo = makeDo(apply); // dry-run logs the DELETEs; --apply executes them
+  let killed = 0, marked = 0, errors = 0;
+
+  // ZOMBIES: a droplet no live row owns. Force-delete it (idempotent + retried),
+  // then tear down its edge. The box row (if any) is already 'destroyed'/'error' —
+  // we don't change DB state, we reclaim the leaked DO resource + record an audit row.
+  for (const z of zombies) {
+    const who = z.login ? `@${z.login}` : `droplet ${z.dropletId}`;
+    if (!apply) { console.log(`  would FORCE-DELETE zombie droplet ${z.dropletId} (${z.name || '?'}, ${who})`); continue; }
+    try {
+      const r = await deleteWithRetry(() => mutateDo.deleteDroplet(z.dropletId));
+      if (!r.ok) throw r.error || new Error('droplet delete failed');
+      await teardownEdgeForLogin(z.login, { apply });
+      const row = boxRows.find((b) => b.builder_id === z.builderId);
+      if (row) {
+        await boxes.recordEvent(pool, {
+          boxId: row.id, builderId: z.builderId, event: 'deprovision',
+          detail: `drift: zombie droplet ${z.dropletId} force-deleted (row was '${row.state}')`,
+          actor: 'reconcile:drift',
+        });
+      }
+      killed++;
+      console.log(`  ✓ killed zombie droplet ${z.dropletId} (${who})`);
+    } catch (e) {
+      errors++;
+      console.log(`  ✖ zombie droplet ${z.dropletId} (${who}): ${e.message}`);
+    }
+  }
+
+  // GHOSTS: a live row whose droplet is gone from DO. Accrue final compute, tear
+  // down any leftover edge, then mark 'destroyed' (clearing the dead droplet_id +
+  // SSH host keys, idea 310) so the DB stops claiming a running box.
+  for (const g of ghosts) {
+    if (!apply) { console.log(`  would MARK DESTROYED @${g.login || g.builderId}'s box (state '${g.state}', droplet ${g.dropletId} gone from DO)`); continue; }
+    try {
+      const row = boxRows.find((b) => b.builder_id === g.builderId);
+      const nowMs = Date.now();
+      if (row && row.state === 'active' && row.droplet_id) {
+        await boxes.recordComputeCost(pool, { box: row, untilMs: nowMs, actor: 'reconcile:drift' });
+      }
+      await teardownEdgeForLogin(g.login, { apply });
+      await boxes.setBoxState(pool, g.builderId, 'destroyed', {
+        destroyed_at: new Date(nowMs), droplet_id: null, ip: null, snapshot_id: null,
+        active_since: null, parked_at: null, claude_active: false,
+        host_keys: null, host_keys_at: null,
+      });
+      if (row) {
+        await boxes.recordEvent(pool, {
+          boxId: row.id, builderId: g.builderId, event: 'deprovision',
+          detail: `drift: droplet ${g.dropletId} vanished from DO — row '${g.state}'→'destroyed'`,
+          actor: 'reconcile:drift',
+        });
+      }
+      marked++;
+      console.log(`  ✓ marked @${g.login || g.builderId}'s box destroyed (ghost droplet ${g.dropletId})`);
+    } catch (e) {
+      errors++;
+      console.log(`  ✖ ghost @${g.login || g.builderId}: ${e.message}`);
+    }
+  }
+
+  console.log(`done — zombies-killed=${killed} ghosts-marked=${marked} errors=${errors} dry-run=${!apply}`);
+  return { zombies: killed, ghosts: marked, errors };
+}
+
+// ---- run-intents (#701: drain the auto-provision / wake-on-connect queue) --
+
+// The control-plane half of the #701 onboarding middleware. The web process can
+// only ENQUEUE a provision/wake intent (POST /box/ensure) — it never holds the DO
+// token. This subcommand, run on a short systemd timer (box-intent-runner.timer,
+// every minute), drains box_intents by calling the SAME cmdProvision/cmdWake the
+// operator uses. DRY-RUN DEFAULT: without --apply it only lists the pending queue
+// (and does NOT claim rows). With --apply it claims + executes each pending intent.
+//
+// A small attempt cap (BOX_INTENT_MAX_ATTEMPTS, default 3) retires a poison intent
+// to 'error' so a doomed provision can't loop forever burning the DO API.
+const MAX_INTENT_ATTEMPTS = numEnv('BOX_INTENT_MAX_ATTEMPTS', 3);
+
+async function cmdRunIntents(pool, boxes, boxOnboard, { apply }) {
+  if (!apply) {
+    const { rows } = await pool.query(
+      `SELECT bi.*, b.github_login FROM box_intents bi
+         JOIN builders b ON b.id = bi.builder_id
+        WHERE bi.state = 'pending' ORDER BY bi.created_at`
+    );
+    console.log(`intent runner (dry-run): ${rows.length} pending intent(s)`);
+    for (const r of rows) console.log(`  would ${r.action} @${r.github_login} (intent #${r.id}, attempts=${r.attempts})`);
+    if (rows.length === 0) console.log('  queue empty — exit clean');
+    return { ran: 0 };
+  }
+
+  let ran = 0, ok = 0, errors = 0;
+  // Drain the queue one claimed intent at a time (FOR UPDATE SKIP LOCKED), so two
+  // overlapping runner ticks never execute the same intent.
+  for (;;) {
+    const intent = await boxes.claimNextIntent(pool);
+    if (!intent) break;
+    ran++;
+    const builder = await resolveBuilder(pool, String(intent.builder_id));
+    const who = builder ? `@${builder.github_login}` : `builder#${intent.builder_id}`;
+    // Poison guard: a claimed intent already past the cap is retired, not retried.
+    if (intent.attempts > MAX_INTENT_ATTEMPTS) {
+      await boxes.resolveIntent(pool, intent.id, 'error', `exceeded ${MAX_INTENT_ATTEMPTS} attempts`);
+      errors++;
+      console.log(`  ✖ ${who}: intent #${intent.id} retired (too many attempts)`);
+      continue;
+    }
+    console.log(`  ${intent.action} ${who} (intent #${intent.id}, attempt ${intent.attempts})`);
+    try {
+      const ref = String(intent.builder_id);
+      const result = intent.action === 'provision'
+        ? await cmdProvision(pool, boxes, boxOnboard, ref, { apply: true })
+        : intent.action === 'deprovision'
+          ? await cmdDeprovision(pool, boxes, ref, { apply: true })
+          : await cmdWake(pool, boxes, ref, { apply: true });
+      if (result && result.ok === false) {
+        // Leave it 'pending' for a retry UNLESS we've hit the cap (next claim
+        // bumps attempts; the guard above retires it once over the cap).
+        if (intent.attempts >= MAX_INTENT_ATTEMPTS) {
+          await boxes.resolveIntent(pool, intent.id, 'error', result.error || 'lifecycle op failed');
+        } else {
+          await pool.query(`UPDATE box_intents SET state = 'pending', last_error = $2, updated_at = now() WHERE id = $1`,
+            [intent.id, result.error || 'lifecycle op failed']);
+        }
+        errors++;
+        console.log(`  ✖ ${who}: ${result.error || 'failed'}`);
+      } else {
+        await boxes.resolveIntent(pool, intent.id, 'done', null);
+        ok++;
+        console.log(`  ✓ ${who}: ${intent.action} done`);
+      }
+    } catch (e) {
+      await boxes.resolveIntent(pool, intent.id, 'error', e.message).catch(() => {});
+      errors++;
+      console.log(`  ✖ ${who}: ${e.message}`);
+    }
+  }
+  console.log(`done — ran=${ran} ok=${ok} errors=${errors}`);
+  return { ran, ok, errors };
+}
+
+// ---- status ----------------------------------------------------------------
+
+async function cmdStatus(pool, boxes) {
+  const rows = await boxes.listBoxes(pool, {});
+  if (rows.length === 0) { console.log('no builder boxes yet.'); return; }
+  let monthly = 0, spent = 0;
+  console.log('builder boxes:');
+  for (const b of rows) {
+    const sz = boxes.SIZE_CATALOG[b.size_slug];
+    const liveMo = b.state === 'active' && sz ? sz.monthlyUsd : 0;
+    monthly += liveMo;
+    spent += Number(b.compute_cost_usd || 0);
+    const where = b.state === 'active' ? `${b.ip || '?'} (${b.size_slug})` : b.state === 'parked' ? `snapshot ${b.snapshot_id || '?'}` : '';
+    console.log(`  @${b.github_login.padEnd(16)} ${b.state.padEnd(12)} scope=${b.scope.padEnd(8)} $${Number(b.compute_cost_usd || 0).toFixed(2)} spent  ${where}`);
+  }
+  console.log(`\n  active monthly run-rate: ~$${monthly.toFixed(2)}/mo   total compute spent: $${spent.toFixed(2)}`);
+}
+
+// ---- shared ----------------------------------------------------------------
+
+let APPLY = false;
+function actorTag() {
+  const who = process.env.GDS_ACTOR || process.env.USER || 'cli';
+  return `cli:${who}`;
+}
+function fail(msg) { console.error(`✖ ${msg}`); return { ok: false, error: msg }; }
+
+function usage() {
+  console.log(`box.js — per-builder dev box lifecycle (ADR 0031 §2/§5, #598)
+
+Usage:
+  node scripts/gds/box.js <command> [args] [--apply]
+
+Commands:
+  provision <builder>    create + boot a box (rank-gated, floor=${CONFIG.floor})
+  onboard <builder>      provision + print the builder welcome packet (#685);
+                         requires a registered SSH key unless --allow-no-keys
+  park <builder>         snapshot + destroy droplet (stop compute billing)
+  wake <builder>         recreate droplet from its snapshot
+  deprovision <builder>  destroy droplet AND snapshot (full reclaim)
+  run-intents            drain the auto-provision/wake-on-connect queue (#701):
+                         execute each pending box_intents row (provision/wake)
+  sweep-idle             park active boxes idle > ${CONFIG.idleMinutes}m
+  sweep-dormant          deprovision boxes parked > ${CONFIG.dormantDays}d (pings builder)
+  reconcile              source-access clawback: deprovision below-floor/inactive
+                         boxes, rescope graduated ones (ADR 0031 §6, #600)
+  reconcile-drift        repair DO⇄DB drift BOTH ways (task 1289): force-delete
+                         zombie droplets (running but no live box row) + mark
+                         ghost rows destroyed (droplet gone from DO)
+  status                 print the box roster + cost
+
+DRY-RUN IS DEFAULT. Pass --apply to actually touch DigitalOcean + the DB.
+<builder> = GitHub login or numeric builder id.
+
+Named browser-terminal tunnel (#771, ADR 0038 — OPT-IN, default OFF):
+  BOX_NAMED_TUNNEL=1        turn on per-builder named Cloudflare tunnels (provision
+                            creates term-<login>.${CF.terminalZone} + bakes the
+                            connector token; deprovision tears it down). Off → the
+                            zero-secret quick tunnel (trycloudflare.com).
+  CLOUDFLARE_API_TOKEN      token with Account:Cloudflare Tunnel:Edit + Zone:DNS:Edit
+  CLOUDFLARE_ACCOUNT_ID     the Cloudflare account the tunnels live in
+  CLOUDFLARE_ZONE           DNS zone (default ${CF.zone})
+  BOX_TERMINAL_ZONE         hostname suffix (default ${CF.terminalZone})`);
+}
+
+// box.js is a CLI: run directly it dispatches; require()d (only by tests — prod
+// never imports it, it is always spawned) it exposes the orchestration fns so the
+// dry-run/live contract can be exercised with injected fakes (#1034). The guard
+// keeps a require() from running the CLI + calling process.exit.
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = args[0];
+  APPLY = hasFlag(args, '--apply');
+  if (!cmd || cmd === '--help' || cmd === '-h' || cmd === 'help') { usage(); process.exit(0); }
+
+  const known = ['provision', 'onboard', 'park', 'wake', 'deprovision', 'run-intents', 'sweep-idle', 'sweep-dormant', 'reconcile', 'reconcile-drift', 'status'];
+  if (!known.includes(cmd)) { console.error(`unknown command: ${cmd}\n`); usage(); process.exit(2); }
+
+  const ref = args[1] && !args[1].startsWith('--') ? args[1] : null;
+  const needsRef = ['provision', 'onboard', 'park', 'wake', 'deprovision'].includes(cmd);
+  if (needsRef && !ref) { console.error(`${cmd} needs a <builder> (login or id)`); process.exit(2); }
+
+  let pool, boxes, boxAccess, boxOnboard;
+  try { ({ pool, boxes, boxAccess, boxOnboard } = loadDeps()); }
+  catch (e) { console.error(`cannot load DB layer (run this on the control plane / droplet): ${e.message}`); process.exit(1); }
+
+  let result;
+  try {
+    const opts = { apply: APPLY, allowNoKeys: hasFlag(args, '--allow-no-keys') };
+    if (cmd === 'provision') result = await cmdProvision(pool, boxes, boxOnboard, ref, opts);
+    else if (cmd === 'onboard') result = await cmdOnboard(pool, boxes, boxOnboard, ref, opts);
+    else if (cmd === 'park') result = await cmdPark(pool, boxes, ref, opts);
+    else if (cmd === 'wake') result = await cmdWake(pool, boxes, ref, opts);
+    else if (cmd === 'deprovision') result = await cmdDeprovision(pool, boxes, ref, opts);
+    else if (cmd === 'run-intents') result = await cmdRunIntents(pool, boxes, boxOnboard, opts);
+    else if (cmd === 'sweep-idle') result = await cmdSweepIdle(pool, boxes, opts);
+    else if (cmd === 'sweep-dormant') result = await cmdSweepDormant(pool, boxes, opts);
+    else if (cmd === 'reconcile') result = await cmdReconcile(pool, boxes, boxAccess, opts);
+    else if (cmd === 'reconcile-drift') result = await cmdReconcileDrift(pool, boxes, opts);
+    else if (cmd === 'status') result = await cmdStatus(pool, boxes);
+  } catch (e) {
+    console.error('fatal:', e && e.message ? e.message : e);
+    await pool.end().catch(() => {});
+    process.exit(1);
+  }
+  await pool.end().catch(() => {});
+  process.exit(result && result.ok === false ? 1 : 0);
+}
+
+if (require.main === module) main();
+
+module.exports = { cmdProvision, deprovisionOne, deleteWithRetry, cmdReconcileDrift, runDnsHook, runDnsHookBlackhole, markErrorUnlessDestroyed };