@bongos/core 1.19.1073 → 1.19.1075

package/scripts/gds/box.js

@@ -1,1332 +0,0 @@
-#!/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
-// must RUN ON A TRUSTED CONTROL PLANE (the prod droplet or an operator's machine),
-// NOT inside a builder box — a box provisioning boxes is privilege escalation, and
-// the builder firewall doesn't even allow-list the DO API. The rank gate reads the
-// builder's LIVE DB rank (what 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            PARK every active box idle > BOX_IDLE_MINUTES (snapshot kept)
-//   sweep-dormant         warn, then deprovision every box parked > BOX_DORMANT_DAYS
-//                         (the ONLY automated path that destroys a snapshot)
-//   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
-// without --apply, so run any command bare first to see the plan (as with
-// `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_UNATTENDED_MAX_HOURS (12), 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, '..', '..');
-
-// The box cloud-init (infra/builder-box-cloud-init.yaml + its ~9 gz+b64-inlined
-// scripts) is INSTANCE content, deliberately NOT shipped in @bongos/core (the R89
-// packaging split). On a VENDORED instance box.js runs from
-// node_modules/@bongos/core, so REPO_ROOT/infra does not exist — and the box then
-// boots BARE (no clone, no toolchain, no terminal). So resolve infra/ from the
-// INSTANCE root, riding ADR 0108's resolvers, instead of assuming it sits beside
-// box.js. ADR 0150 (BV1.R97/R98).
-const instanceConfig = require(path.join(REPO_ROOT, 'src/instance-config'));
-const { installedCoreVersion, runnerBanner } = require('./runner-drift.js');
-const { coreVersionSafe } = require('./provision-config.js');
-const BOX_INFRA_TEMPLATE = 'builder-box-cloud-init.yaml';
-
-// Ordered candidate infra/ dirs — first that actually holds the cloud-init
-// template wins. Pure (env + repoRoot injected) so it is unit-testable without
-// touching the real filesystem layout.
-const { CF, CONFIG, boxInfraCandidates, dropletName, hasFlag, hostnameFor, numEnv, readCloudInit, resolveBoxInfraDir, runDnsHook, runDnsHookBlackhole, shortStamp } = require('./box-infra.js');
-function namedTunnelEnabled() { return CF.enabled; }
-function namedTunnelConfigured() { return CF.enabled && CF.apiToken && CF.accountId; }
-
-function makeCf(apply) {
-  const { CfTunnelApi } = loadDeps();
-  return new CfTunnelApi({
-    dryRun: !apply,
-    token: CF.apiToken,
-    accountId: CF.accountId,
-    log: (m) => console.log('  ' + m),
-  });
-}
-
-// SECURITY PREFLIGHT (task 1002511, ADR 0053 / SR#11). The edge cookie-strip
-// Transform Rule is applied BEST-EFFORT deep inside ensureNamedTunnel, so a
-// CLOUDFLARE_API_TOKEN missing the zone "Transform Rules" edit scope fails as one
-// buried log line while the apex session cookie keeps reaching box subdomains. This
-// probe runs BEFORE any DigitalOcean spend (dry-run included — a read-only lookup in
-// a plan is the drift-reconcile precedent) and shouts the exact fix.
-//
-// HONESTY: the probe is a GET, so it can only DISPROVE the scope. A readable phase
-// does NOT mean the rule can be written — only the PUT inside ensureNamedTunnel
-// proves that. Never print this as a confirmed control. Never blocks provisioning:
-// the rule is defense-in-depth and a box without it still works.
-async function preflightCookieStripScope() {
-  const { cfTunnel } = loadDeps();
-  let scope;
-  try {
-    scope = await cfTunnel.checkRulesetScope({
-      zone: CF.zone, phase: cfTunnel.COOKIE_STRIP_PHASE, token: CF.apiToken,
-    });
-  } catch (e) {
-    scope = { readable: false, reason: `ruleset preflight crashed: ${e.message}`, guidance: '' };
-  }
-  if (scope.readable) {
-    console.log(`  cookie-strip ruleset is readable on ${CF.zone} — edit scope stays UNPROVEN until the rule is applied (ADR 0053)`);
-    return scope;
-  }
-  console.log('');
-  console.log('  ⚠⚠ SECURITY (ADR 0053 / SR#11) — the edge cookie-strip rule cannot be confirmed');
-  console.log(`     ${scope.reason}`);
-  console.log(`     IMPACT: the apex session cookie (Domain=.${CF.zone}) is sent by the browser to`);
-  console.log(`             term-*.${CF.terminalZone} and sandbox-*.${CF.terminalZone} — hosts OUTSIDE the`);
-  console.log('             ADR 0016 trust boundary — until that Transform Rule is actually in place.');
-  if (scope.guidance) console.log(`     FIX: ${scope.guidance}`);
-  console.log('     Provisioning CONTINUES — this is defense-in-depth, never a provisioning gate.');
-  console.log('');
-  return scope;
-}
-
-// Lazily-built handles to the heavy dependencies (DB pool, DO/CF clients), so a
-// dry-run or a --help never opens a pool or requires a network client.
-//
-// task 1003507 — this was UNDECLARED. `_deps = {...}` further down is an
-// assignment, which in sloppy mode would have created a global, but
-// `if (_deps)` READS it first, and reading an undeclared identifier is a
-// ReferenceError. So loadDeps() threw on its first call, every time, and every
-// command that reaches makeDo()/makeCf() went with it — including
-// `sweep-idle --apply`, which resolves its DO client before the park loop.
-// The idle sweep therefore could not park ANY box, which is a second and
-// entirely separate reason the abandoned box in this task was never reaped.
-// No test caught it because the only apply:true test relied on the
-// claude_active veto emptying the idle set before makeDo() was reached.
-let _deps = null;
-
-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 cfTunnel = require(path.join(REPO_ROOT, 'scripts/gds/cf-tunnel'));
-  _deps = { pool, boxes, boxAccess, boxOnboard, DoApi, CfTunnelApi: cfTunnel.CfTunnelApi, cfTunnel };
-  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).
-// ---- provision -------------------------------------------------------------
-
-// Pure: renders the /etc/otb/box.env content cloud-init bakes onto a box (task
-// 1002466). Split out of cmdProvision so GDS_BASE — and the named-tunnel block
-// baked in beside it — can be unit-tested without DB/DO/Cloudflare.
-//
-// GDS_BASE is the FULL api base (origin + /api/bongos), matching what
-// infra/box-report-*.sh already derive from the session file when the env var is
-// absent (`"$GDS_BASE/box/host-keys"` with no further path inserted) — every box
-// used to get this only as a fallback derived on-box; baking it explicitly closes
-// the one on-box script (box-source-fetch.sh, out-of-repo) that skips that
-// derivation entirely and hardcodes a different instance's origin instead.
-function buildBoxEnv({ apiOrigin, namedTunnel }) {
-  let env = `# /etc/otb/box.env — baked by box.js provision\nGDS_BASE=${String(apiOrigin).replace(/\/+$/, '')}/api/bongos\n`;
-  if (namedTunnel) {
-    const { token, hostname, credential, previewHostname } = namedTunnel;
-    env += `# named tunnel (#771/#774, ADR 0038)\nBOX_TUNNEL_TOKEN=${token}\nBOX_TERMINAL_HOSTNAME=${hostname}\nBOX_TERMINAL_CREDENTIAL=${credential}\nBOX_PREVIEW_HOSTNAME=${previewHostname}\n`;
-  }
-  return env;
-}
-
-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`)' : ''}`);
-
-  // ADR 0150 — resolve the box cloud-init source up front (dry-run AND apply) and
-  // FAIL LOUD if it can't be located. A missing infra/ means empty user-data, i.e.
-  // a box that boots BARE. Aborting here (before any session/tunnel is minted)
-  // surfaces the packaging bug in the PLAN, not as a silent bare box hours later.
-  const infraDir = resolveBoxInfraDir();
-  if (!infraDir) {
-    return fail(
-      `box cloud-init source not found — no infra/${BOX_INFRA_TEMPLATE} in any candidate location `
-      + `(<PREFIX>_BOX_INFRA_DIR, <PREFIX>_INSTANCE_ROOT / bongos.config.json, ${path.join(REPO_ROOT, 'infra')}, or a node_modules ancestor). `
-      + `A box would boot BARE — refusing to provision. Ship infra/ or point the instance root at it (ADR 0150).`,
-    );
-  }
-  console.log(`  cloud-init source: ${infraDir}`);
-
-  // 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})`);
-    // Before ANY droplet spend, and on the dry-run path too, so `provision <login>`
-    // with no --apply tells the operator the truth for free (task 1002511).
-    await preflightCookieStripScope();
-  } 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. So 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 placed
-  // on the box and no box-side reporter (the quick-tunnel fallback that caused the
-  // #771/#774 chicken-and-egg). ADR 0016 holds — no credential funneled into a box.
-  // GDS_BASE (task 1002466 — see buildBoxEnv above for the shape/why): a box was
-  // never actually bare here EXCEPT the one on-box script that skips the
-  // session-file fallback (box-source-fetch.sh, out-of-repo on the control-plane
-  // — see the cross-repo blocker filed alongside this fix). Baking it explicitly
-  // closes that gap for every future box regardless of which script forgets it.
-  const apiOrigin = instanceConfig.resolveEnv('PUBLIC_ORIGIN') || instanceConfig.defaultApiBase();
-  let boxEnv = buildBoxEnv({ apiOrigin });
-  let terminalHostname = null;
-  let terminalCredential = null;
-  if (namedTunnelEnabled()) {
-    try {
-      const { token, hostname: th, previewHostname: ph, edgeRules } = 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 = buildBoxEnv({
-        apiOrigin,
-        namedTunnel: { token, hostname: th, credential: terminalCredential, previewHostname: ph },
-      });
-      console.log(`  ✓ named tunnel ready — ${th}`);
-      console.log(`  ✓ live game preview — https://${ph} (ADR 0044)`);
-      // The rule PUT is the ONLY thing that proves edit scope. Report its real
-      // outcome next to the ✓ lines so a silent miss lands in the summary rather
-      // than mid-log (task 1002511).
-      if (edgeRules && !edgeRules.cookieStrip.applied) {
-        console.log(`  ⚠⚠ SECURITY (ADR 0053 / SR#11): the edge cookie-strip Transform Rule was NOT applied${edgeRules.cookieStrip.error ? ` — ${edgeRules.cookieStrip.error}` : ''}`);
-        console.log(`     Platform cookies for .${CF.zone} can reach ${th} and ${ph} until it is.`);
-        console.log('     Widen CLOUDFLARE_API_TOKEN with zone "Transform Rules → Edit", or apply the rule');
-        console.log('     once by hand — see docs/recipes/builder-box-lifecycle.md.');
-      }
-      if (edgeRules && !edgeRules.cacheBypass.applied) {
-        console.log(`  ⚠ the sandbox cache-bypass Cache Rule was NOT applied${edgeRules.cacheBypass.error ? ` — ${edgeRules.cacheBypass.error}` : ''} (stale preview risk, #1065)`);
-      }
-    } 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; with no session file
-  // it no-ops forever (repo never clones → no devcontainer, no /builder-* skills),
-  // and the session normally comes from /builder-setup, which lives in the un-cloned
-  // repo — the chicken-and-egg. So mint one here and bake it into cloud-init.
-  //
-  // SECURITY (#919, SR#2): this baked session is source='box' — SCOPED, 24h
-  // refresh-on-use. The token sits ON the box (any on-box process + the metadata
-  // endpoint can read it), OUTSIDE the ADR 0016 trust boundary, so it must not carry
-  // the builder's full authority: requireBuilder denies a 'box' session everywhere
-  // except the 4 on-box cron routes (source-access, authorized-keys, heartbeat,
-  // terminal — via auth.allowBoxScope). Real work FROM the box needs /builder-reauth
-  // (device flow); user_agent='box-provision' is the marker migration 090 keys on.
-  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 },
-    // The instance's OWN public origin (task 1002428) — a hardcoded founder host
-    // here would point every newly provisioned box at the wrong instance.
-    //
-    // defaultApiBase(), deliberately NOT resolveApiBase() (task 1002466): a box
-    // belongs to the SERVER it was provisioned on, not to whichever instance this
-    // operator's own CLI session happens to be signed into right now — the two can
-    // differ (an operator provisioning boxes across instances) and the box must
-    // still call home to itself, not to the operator's other login.
-    api_base: instanceConfig.resolveEnv('PUBLIC_ORIGIN') || instanceConfig.defaultApiBase(),
-  }, 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.
-  let userData;
-  try {
-    userData = readCloudInit({ authorizedKeysBlock, boxEnv, gdsSession, infraDir });
-  } catch (e) {
-    await boxes.setBoxState(pool, builder.id, 'error', { error_note: `cloud-init: ${e.message}`.slice(0, 480) });
-    return fail(e.message);
-  }
-  const userDataBytes = userData ? Buffer.byteLength(userData, 'utf8') : 0;
-  // Belt-and-braces (ADR 0150): readCloudInit throws above, but NEVER hand DO empty
-  // user-data — that IS the bare-box failure this fix closes.
-  if (!userDataBytes) {
-    await boxes.setBoxState(pool, builder.id, 'error', { error_note: 'cloud-init render produced empty user-data' });
-    return fail('cloud-init render produced EMPTY user-data — a box would boot bare (ADR 0150); refusing to provision.');
-  }
-  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,
-    // The droplet about to boot mints FRESH host keys, so anything the row still
-    // carries describes a box that is gone. deprovisionOne clears these on teardown
-    // (idea 310), but a provision over a row that never went through teardown — an
-    // errored/parked box, a re-provision after a manual DO delete — kept serving the
-    // predecessor's identity via GET /box/me, and the connect path pinned it: "Host
-    // denied (verification failed)". Clear here too; the new box re-reports via
-    // POST /box/host-keys, and until then the client falls back to a live keyscan.
-    host_keys: null, host_keys_at: 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.
-// The instance's product name, for the Claude Desktop environment label the
-// connect instructions name (task 1002428). Neutral fallback, never a foreign brand.
-function boxEnvLabel() {
-  try {
-    const id = require(path.join(REPO_ROOT, 'src/branding')).branding().identity || {};
-    if (id.productName) return id.productName;
-  } catch (_) { /* fall through */ }
-  return 'Cloud Bongos';
-}
-
-function gdsBase() {
-  // Session-aware, via the single source of truth (task 1002427/1002428) — the
-  // operator's signed-in instance, not a hardcoded founder host. <PREFIX>_API_BASE
-  // (incl. legacy GDS_API_BASE) still wins, so existing overrides are unchanged.
-  return String(instanceConfig.resolveApiBase()).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/bongos/box/connect.sh | bash`);
-  console.log(`  Windows:      irm ${base}/api/bongos/box/connect.ps1 | iex`);
-  console.log(`  (guide:       ${base}/api/bongos/box/connect )`);
-  console.log('');
-  console.log(`Then: restart Claude Desktop → Code → Environment → "${boxEnvLabel()} 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/bongos/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/bongos/box/connect.sh | bash`);
-    console.error(`    Windows:      irm ${gdsBase()}/api/bongos/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,
-    // task 1003507 — the droplet is gone, so there is no `claude` process to
-    // report. Clearing the flag AND its clock here means a wake starts a fresh
-    // session rather than inheriting an expired latch and being reaped at once.
-    claude_active: false, claude_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,
-      // task 1003507 — a woken box has reported nothing yet. Start the latch and
-      // its clock clean so the first real heartbeat sets both, rather than the
-      // box re-entering the sweep carrying a stale claim from its last session.
-      claude_active: false, claude_active_since: 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, claude_active_since: null,
-    // 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 PARKED: snapshot taken, droplet destroyed (compute billing
-// stops), filesystem preserved so the builder wakes into their work. Snapshot
-// storage is ~$0.30/mo — the price of not silently discarding uncommitted work.
-//
-// This sweep deliberately never destroys a snapshot. Full reclaim (droplet AND
-// snapshot) belongs to sweep-dormant, which only fires after BOX_DORMANT_DAYS of
-// being parked and pings the builder first. That split is the whole safety
-// property: no automated path can take work off a builder without warning.
-//
-// History: this sweep used to call deprovisionOne directly, on the theory that
-// boxes are ephemeral and builders provision fresh each session. In practice it
-// meant a box idle past the threshold was annihilated — droplet and snapshot —
-// taking anything uncommitted with it, while the CLI help, the /builder-box
-// skill and the hall all still described park-and-wake. Task 1002726 restored
-// the documented behaviour rather than the documentation.
-
-async function cmdSweepIdle(pool, boxes, { apply }) {
-  const rows = await boxes.listBoxes(pool, { state: 'active' });
-  const sweepNow = Date.now();
-  const sel = { idleMinutes: CONFIG.idleMinutes, nowMs: sweepNow, unattendedMaxHours: CONFIG.unattendedMaxHours };
-  const idle = boxes.selectIdleBoxes(rows, sel);
-  console.log(`idle sweep (threshold=${CONFIG.idleMinutes}m, unattended cap=${CONFIG.unattendedMaxHours}h${apply ? '' : ', dry-run'}): ${idle.length} of ${rows.length} active box(es) idle`);
-  if (idle.length === 0) { console.log('  nothing idle — exit clean'); return { parked: 0 }; }
-  const doApi = apply ? makeDo(apply) : null;
-  let parked = 0, errors = 0;
-  for (const box of idle) {
-    const why = boxes.idleReason(box, sel);
-    if (!apply) { console.log(`  would park @${box.github_login}'s box (${why}, droplet ${box.droplet_id})`); continue; }
-    try {
-      await parkOne(pool, boxes, doApi, box, { actor: 'sweep:idle' });
-      parked++;
-      console.log(`  ✓ parked @${box.github_login} (${why} — snapshot kept, compute stopped)`);
-    } catch (e) {
-      // A park that fails must NOT fall through to a destroy — leaving the box
-      // at 'error' with its droplet intact is strictly safer than reclaiming it,
-      // and reconcile-drift picks the row up from there.
-      errors++;
-      await markErrorUnlessDestroyed(pool, boxes, box.builder_id, e.message);
-      console.log(`  ✖ @${box.github_login}: ${e.message}`);
-    }
-  }
-  console.log(`done — parked=${parked} errors=${errors} dry-run=${!apply}`);
-  return { parked, errors };
-}
-
-// ---- sweep-dormant ---------------------------------------------------------
-// Task 1002727 — since the idle sweep parks rather than destroys (task 1002726),
-// this is the ONLY automated path that deletes a snapshot, i.e. the only one that
-// can take a builder's uncommitted work. So it warns before it takes: a box
-// entering the warning window gets one heads-up, and a box past the threshold is
-// reclaimed ONLY if that warning was actually delivered during its current parked
-// interval. If it never was — runner downtime, a chat outage, a box that sailed
-// past the window while the sweep was off — the reclaim is DEFERRED and the
-// warning is sent instead. That way "no automated path silently discards work"
-// holds even when the machinery itself misbehaves.
-
-async function cmdSweepDormant(pool, boxes, { apply }) {
-  const rows = await boxes.listBoxes(pool, { state: 'parked' });
-  const now = Date.now();
-  const dormant = boxes.selectDormantBoxes(rows, { dormantDays: CONFIG.dormantDays, nowMs: now });
-  const warnAt = Math.max(CONFIG.dormantDays - CONFIG.dormantWarnLeadDays, 0);
-  const warning = boxes.selectDormantWarnBoxes(rows, {
-    dormantDays: CONFIG.dormantDays, warnLeadDays: CONFIG.dormantWarnLeadDays, nowMs: now,
-  });
-  console.log(`dormant sweep (reclaim >${CONFIG.dormantDays}d, warn >${warnAt}d${apply ? '' : ', dry-run'}): ${dormant.length} dormant, ${warning.length} entering the warning window, of ${rows.length} parked`);
-  if (dormant.length === 0 && warning.length === 0) { console.log('  nothing dormant — exit clean'); return { reclaimed: 0, warned: 0, deferred: 0 }; }
-  // Built lazily: a sweep that only WARNS must not require a DO token.
-  let doApi = null;
-  const needDo = () => (doApi || (doApi = makeDo(apply)));
-  let reclaimed = 0, errors = 0, pingFailed = 0, warned = 0, deferred = 0;
-
-  const sendWarning = async (box, days) => {
-    const left = Math.max(CONFIG.dormantDays - days, 0);
-    const ping = postReclaimPing(`@${box.github_login} — your dev box has been parked ${days} days. Its saved disk image will be reclaimed in ${left} day(s) to save cost, and anything on it you haven't pushed will be gone with it. Wake it any time with POST /api/bongos/box/ensure to keep it.`);
-    if (!ping.ok) { pingFailed++; return false; }
-    await boxes.recordEvent(pool, {
-      boxId: box.id, builderId: box.builder_id, event: 'dormant_warning',
-      detail: `parked ${days}d; reclaim in ${left}d`, actor: 'sweep:dormant',
-    });
-    warned++;
-    return true;
-  };
-
-  for (const box of warning) {
-    const days = Math.round((now - Date.parse(box.parked_at)) / 86400000);
-    if (!apply) { console.log(`  would warn @${box.github_login} (parked ${days}d)`); continue; }
-    if (await boxes.hasDormantWarning(pool, { boxId: box.id, parkedAt: box.parked_at })) continue;
-    const ok = await sendWarning(box, days);
-    console.log(`  ${ok ? '✓ warned' : '✖ warning FAILED for'} @${box.github_login} (parked ${days}d)`);
-  }
-
-  for (const box of dormant) {
-    const days = Math.round((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; }
-    // The gate: no receipt, no reclaim. Warn now, let a later sweep take it.
-    if (!(await boxes.hasDormantWarning(pool, { boxId: box.id, parkedAt: box.parked_at }))) {
-      deferred++;
-      const ok = await sendWarning(box, days);
-      console.log(`  ⏸ deferred @${box.github_login} (parked ${days}d) — never warned; ${ok ? 'warning sent, reclaim next sweep' : 'warning FAILED, will retry'}`);
-      continue;
-    }
-    try {
-      await deprovisionOne(pool, boxes, needDo(), box, { actor: 'sweep:dormant' });
-      reclaimed++;
-      const ping = postReclaimPing(`@${box.github_login} — your dev box was parked for ${days} days and has now been reclaimed to save cost, as warned. Queue a fresh one anytime with POST /api/bongos/box/ensure (no operator needed); 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} warned=${warned} deferred=${deferred} ping-failed=${pingFailed} errors=${errors} dry-run=${!apply}`);
-  return { reclaimed, warned, deferred, 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, claude_active_since: null,
-        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 }) {
-  const instanceRoot = process.env.BONGOS_INSTANCE_ROOT || process.cwd();
-  console.log(runnerBanner({ runnerVersion: coreVersionSafe(), runnerRoot: REPO_ROOT, instanceVersion: installedCoreVersion(instanceRoot), instanceRoot }));
-  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 = instanceConfig.resolveEnv('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, or unattended > ${CONFIG.unattendedMaxHours}h
-  sweep-dormant          warn at ${Math.max(CONFIG.dormantDays - CONFIG.dormantWarnLeadDays, 0)}d, then deprovision boxes parked > ${CONFIG.dormantDays}d
-                         (never reclaims a box that was not warned first)
-  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
-                            + Zone:Transform Rules:Edit (the ADR 0053 cookie-strip —
-                            without it platform cookies reach the box subdomains)
-                            + Zone:Cache Rules:Edit (the sandbox cache bypass, #1065).
-                            provision read-probes the ruleset scope before spending.
-  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.
-// provenance() — WHICH core is making this fleet decision, and from which root.
-//
-// Task 1002738: the four cloudbongos-box-* units ran with WorkingDirectory pointed at
-// a root whose vendored @bongos/core was 1.19.2 while the web app had long since moved
-// to 1.19.146 — so every park/destroy/provision decision was made by a core ~145
-// patches behind, including a cmdSweepIdle that still DESTROYED an idle box. Nothing
-// in the journal said so: the sweep banner reports the THRESHOLD but never the code.
-// Diagnosing it took a filesystem dig across two instance roots.
-//
-// One line, printed by every invocation, makes that failure self-announcing: a stale
-// plane now says its own version in `journalctl -u cloudbongos-box-idle-suspend`, next
-// to the instance root that supplied it. Cheap, unconditional, and it can only be
-// wrong if the package it reads is the package it ran.
-// Names the package REPO_ROOT resolved to, not just its version: installed, that is
-// `@bongos/core@1.19.148`; in a monolith checkout it is the instance's own package, and
-// saying so is the point — the line must never let a monolith masquerade as a core pin.
-function provenance() {
-  let pkg = 'unknown';
-  try {
-    const p = require(path.join(REPO_ROOT, 'package.json'));
-    pkg = `${p.name || 'unknown'}@${p.version || 'unknown'}`;
-  } catch { /* a core with no readable package.json still runs — just say unknown */ }
-  const inst = instanceConfig.resolveInstanceRootExplicit() || process.cwd();
-  return `box.js · running from ${pkg} · instance ${inst}`;
-}
-
-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); }
-  console.log(provenance());
-
-  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, cmdRunIntents, deprovisionOne, parkOne, cmdSweepIdle, cmdSweepDormant, deleteWithRetry, cmdReconcileDrift, runDnsHook, runDnsHookBlackhole, markErrorUnlessDestroyed, resolveBoxInfraDir, boxInfraCandidates, readCloudInit, buildBoxEnv, BOX_INFRA_TEMPLATE };