@bongos/core 1.19.1073 → 1.19.1075

package/modules/dev-box/boxes.js

@@ -1,1038 +0,0 @@
-// src/bongos/boxes.js — per-builder cloud dev box lifecycle (ADR 0031 §2 / §5, #598).
-//
-// Two layers in one module, deliberately split:
-//
-//   1. PURE helpers (no I/O) — the rank gate, the size/cost catalog, and the
-//      idle/dormant SELECTION logic. These carry the lifecycle's real decisions,
-//      so they are pure and unit-tested directly (tests/boxes.mjs) with no DB,
-//      no DigitalOcean, no clock — `nowMs` is always injected.
-//
-//   2. DB helpers (async, take the pg pool) — read a builder's box, list the
-//      roster, append a box_events audit row, bump the activity heartbeat, and
-//      the state-transition writers. Shared by BOTH the control-plane CLI
-//      (scripts/gds/box.js) and the read/heartbeat routes (routes/box.js).
-//
-// What is NOT here: the DigitalOcean API calls. Those live in src/bongos/do-api.js
-// (the only network module), and the CLI orchestrator composes pure-guard →
-// DO-call → DB-writer. Keeping DO out of this file is what lets the decisions be
-// tested hermetically.
-//
-// §9.3 (resolved in ADR 0031): auto-suspend = snapshot-and-park. A powered-off
-// DO droplet still bills, so "park" snapshots then DESTROYS the droplet and
-// "wake" recreates from the snapshot. The cost model below reflects that: a box
-// only accrues compute cost while `state='active'`.
-
-// ---------------------------------------------------------------------------
-// PURE: rank gate
-// ---------------------------------------------------------------------------
-
-// Three live ranks (ADR 0018 / migration 029): xenos < metic < archon.
-// ADR 0034 (#692) added `thetes` as the 4th live rank between xenos and metic.
-// It MUST appear here or rankMeetsBoxFloor() fails closed for Thetes (undefined
-// order → below any floor → 403 on /box/ensure), which boxed out the whole tier.
-const RANK_ORDER = { xenos: 0, thetes: 1, metic: 2, archon: 3 };
-
-// Default provisioning floor. ADR 0031 §5(b): a Newcomer (Xenos who has cleared
-// onboarding) gets an org-funded auto-suspended STARTER box — zero payment
-// barrier to begin. So the floor is the lowest live rank; the SCOPE (below)
-// is what differs by rank, not the right to a box. Override with
-// BOX_PROVISION_MIN_RANK to raise it.
-const DEFAULT_PROVISION_FLOOR = 'xenos';
-
-function rankMeetsBoxFloor(rank, floor = DEFAULT_PROVISION_FLOOR) {
-  const r = RANK_ORDER[rank];
-  const f = RANK_ORDER[floor];
-  return Number.isInteger(r) && Number.isInteger(f) && r >= f;
-}
-
-// Source-access scope recorded at provision (consumed by #600). A Xenos or
-// Thetes gets a SCOPED 'starter' surface; a Metic+ gets 'full'. This is the
-// access boundary ADR 0031 §6 / open-question §9.2 describes — #598 records it,
-// #600 enforces it. (ADR 0034: Thetes can hold a box but earns no scope uplift.)
-function boxScopeForRank(rank) {
-  return RANK_ORDER[rank] >= RANK_ORDER.metic ? 'full' : 'starter';
-}
-
-// The provisioning gate. Pure + throwing so it is unit-tested and so the CLI
-// and any future API path enforce the SAME rule (ADR 0016 trust boundary: the
-// check reads the builder's live DB rank, which their machine cannot write).
-function assertProvisionAllowed({ rank, floor = DEFAULT_PROVISION_FLOOR } = {}) {
-  if (!rankMeetsBoxFloor(rank, floor)) {
-    const err = new Error(
-      `INSUFFICIENT_RANK: provisioning a box requires rank >= ${floor}; builder is ${rank ?? 'unknown'}`
-    );
-    err.code = 'INSUFFICIENT_RANK';
-    err.required = floor;
-    err.actual = rank ?? null;
-    throw err;
-  }
-}
-
-// ---------------------------------------------------------------------------
-// PURE: size + cost catalog
-// ---------------------------------------------------------------------------
-
-// DigitalOcean shared-CPU droplet sizes we offer, with their list prices
-// (USD; hourly is the monthly/672 DO rounds to). The default is s-2vcpu-4gb:
-// the devcontainer runs Node 22 + the art pipeline + a dev server, and
-// devcontainer.json sets a 4 GB Node heap — 4 GB RAM is the sane floor. Parked,
-// a box costs only its snapshot (~$0.30/mo for a ~5 GB image), not these rates.
-const SIZE_CATALOG = {
-  's-1vcpu-2gb': { hourlyUsd: 0.01786, monthlyUsd: 12, label: '1 vCPU / 2 GB' },
-  's-2vcpu-2gb': { hourlyUsd: 0.02679, monthlyUsd: 18, label: '2 vCPU / 2 GB' },
-  's-2vcpu-4gb': { hourlyUsd: 0.03571, monthlyUsd: 24, label: '2 vCPU / 4 GB' },
-  's-4vcpu-8gb': { hourlyUsd: 0.07143, monthlyUsd: 48, label: '4 vCPU / 8 GB' },
-};
-const DEFAULT_SIZE = 's-2vcpu-4gb';
-
-function sizeHourlyUsd(slug) {
-  const s = SIZE_CATALOG[slug];
-  return s ? s.hourlyUsd : 0;
-}
-
-// Compute cost of a live interval = hours running × the size's hourly rate.
-// Negative/zero/invalid intervals → 0 (a box that never went active owes nothing).
-function computeActiveCostUsd({ sizeSlug, activeSinceMs, untilMs } = {}) {
-  if (!Number.isFinite(activeSinceMs) || !Number.isFinite(untilMs)) return 0;
-  const ms = untilMs - activeSinceMs;
-  if (ms <= 0) return 0;
-  const hours = ms / 3_600_000;
-  return round4(hours * sizeHourlyUsd(sizeSlug));
-}
-
-// ---- container cost ledger (#602) ----
-// DigitalOcean charges no provision FEE — billing starts at the first active
-// hour, already captured by computeActiveCostUsd. We still log a spin-up LEDGER
-// EVENT (at $0 by default) so the ledger records every create/resume as a
-// timestamped line; override BOX_SPINUP_COST_USD to model a provisioning overhead.
-const SPINUP_COST_USD = Number(process.env.BOX_SPINUP_COST_USD) || 0;
-// A PARKED box keeps only its ~5 GB snapshot (~$0.30/mo). A RUNNING box's disk is
-// included in the droplet hourly rate, so storage is a separate ledger line only
-// while parked. monthly / 730 ≈ hourly.
-const SNAPSHOT_MONTHLY_USD = Number(process.env.BOX_SNAPSHOT_MONTHLY_USD) || 0.30;
-
-// Storage cost of a parked interval = hours parked × the snapshot's hourly rate.
-// Invalid/zero/negative interval → 0.
-function storageCostUsd({ parkedSinceMs, untilMs } = {}) {
-  if (!Number.isFinite(parkedSinceMs) || !Number.isFinite(untilMs)) return 0;
-  const ms = untilMs - parkedSinceMs;
-  if (ms <= 0) return 0;
-  return round4((ms / 3_600_000) * (SNAPSHOT_MONTHLY_USD / 730));
-}
-
-// Pure: bucket cost_log-shaped rows (the box-* sources) into a per-builder
-// summary { spinup_usd, compute_usd, storage_usd, total_usd }. Keyed on `source`
-// so a $0 spin-up line stays distinct from compute. Exported for the cost views
-// + the unit test.
-function summarizeBoxCost(rows) {
-  const out = { spinup_usd: 0, compute_usd: 0, storage_usd: 0, total_usd: 0 };
-  for (const r of rows || []) {
-    const amt = Number(r.amount_usd) || 0;
-    if (r.source === 'box-spinup') out.spinup_usd = round4(out.spinup_usd + amt);
-    else if (r.source === 'box-storage') out.storage_usd = round4(out.storage_usd + amt);
-    else if (r.source === 'box-lifecycle') out.compute_usd = round4(out.compute_usd + amt);
-    out.total_usd = round4(out.total_usd + amt);
-  }
-  return out;
-}
-
-// The cost_log sources this feature owns — the box cost ledger is exactly the
-// rows carrying one of these (compute already shipped under 'box-lifecycle').
-const BOX_COST_SOURCES = ['box-lifecycle', 'box-spinup', 'box-storage'];
-
-function round4(n) {
-  return Math.round((n + Number.EPSILON) * 10000) / 10000;
-}
-
-// ---------------------------------------------------------------------------
-// PURE: idle / dormant selection (the sweep cores)
-// ---------------------------------------------------------------------------
-
-function toMs(ts) {
-  if (ts == null) return null;
-  if (ts instanceof Date) return ts.getTime();
-  const n = Date.parse(ts);
-  return Number.isNaN(n) ? null : n;
-}
-
-// A box's "last activity" for idle purposes: the heartbeat if present, else when
-// the current droplet went active, else when it was first provisioned. The
-// COALESCE means a freshly-provisioned box that has not heartbeated yet is dated
-// from active_since (so it gets a full idle window before its first park, not an
-// instant one).
-function effectiveActivityMs(row) {
-  return toMs(row.last_activity_at) ?? toMs(row.active_since) ?? toMs(row.provisioned_at);
-}
-
-// ---- the unattended cap (task 1003507) ------------------------------------
-//
-// A box used to be able to assert "in use" forever from two proxies, neither of
-// which implies a human is present:
-//
-//   1. `pgrep -x claude` -> claude_active=true, which selectIdleBoxes skipped
-//      with NO time bound. claude_active is a LATCH, not a level: only a
-//      heartbeat ping writes it, and box-heartbeat.sh exits WITHOUT pinging when
-//      it sees nothing — so silence, the very signal the sweep exists to act on,
-//      could never clear it. Unreapable at EVERY threshold, forever.
-//   2. `load > 0.2` -> ACTIVE=1, which keeps bumping last_activity_at. A running
-//      devcontainer plus an idle `claude` clears that floor on its own, so the
-//      activity clock never went stale either.
-//
-// Together they made an abandoned interactive `claude` at its prompt in an
-// UNATTACHED tmux session indistinguishable from a working one, and one such box
-// burned $20.21 of unattended compute the sweep could not reach. Bounding only
-// (1) does not stop the bleeding, because (2) keeps the box out of the idle set
-// on its own — so both proxies are bounded by the same policy:
-//
-//   A box may not stay active for longer than `unattendedMaxHours` without
-//   evidence that a human was actually attached to it.
-//
-// "Attached" is what the heartbeat already knew and used to throw away by
-// folding it into one boolean: a login session (`who`), an established inbound
-// SSH connection, an open browser terminal (ttyd), or an ATTACHED tmux client.
-// It now reports that separately and the server stamps `last_attached_at`.
-const HOUR_MS = 3_600_000;
-
-// Has a human been attached recently enough for this box's claims to stand?
-//   - no cap configured        -> yes (the pre-1003507 unbounded behaviour;
-//                                 the policy lives in the caller's CONFIG)
-//   - last_attached_at unset   -> yes. A box whose heartbeat predates this change
-//                                 never reports attachment, so its column stays
-//                                 NULL forever — treating unknown as unattended
-//                                 would park every such box mid-work. NULL is
-//                                 deliberately NOT backfilled for that reason.
-//   - within the cap           -> yes
-//   - older than the cap       -> no; the box is unattended
-function attendedRecently(row, { nowMs, unattendedMaxHours } = {}) {
-  if (!Number.isFinite(unattendedMaxHours) || unattendedMaxHours <= 0) return true;
-  const at = toMs(row.last_attached_at);
-  if (at == null) return true;
-  return at > nowMs - unattendedMaxHours * HOUR_MS;
-}
-
-// Does claude_active still earn this box a pass from the idle sweep? Bounded by
-// how long it has been claimed, read off `claude_active_since` (migration
-// core_238, stamped on the false->true edge so it measures the whole session
-// rather than the last beat). An unknown age is refused: core_238 backfills every
-// box that is claude_active at deploy, so a NULL stamp under a true flag is the
-// forever-latch this fixes, not a live session.
-function claudeVetoHolds(row, { nowMs, unattendedMaxHours } = {}) {
-  if (!row.claude_active) return false;
-  if (!Number.isFinite(unattendedMaxHours) || unattendedMaxHours <= 0) return true;
-  const since = toMs(row.claude_active_since);
-  if (since == null) return false;
-  return since > nowMs - unattendedMaxHours * HOUR_MS;
-}
-
-// Idle = active boxes that are either (a) quiet past idleMinutes with no live
-// claude_active veto, or (b) still chattering but unattended past the cap. (b) is
-// the abandoned-session case: the heartbeat is fresh, so (a) can never fire.
-// Pure: caller passes the candidate rows and nowMs; returns the subset to park.
-function selectIdleBoxes(rows, { idleMinutes, nowMs, unattendedMaxHours } = {}) {
-  if (!Number.isFinite(idleMinutes) || idleMinutes <= 0) return [];
-  if (!Number.isFinite(nowMs)) return [];
-  const cutoff = nowMs - idleMinutes * 60_000;
-  return (rows || []).filter((r) => {
-    if (r.state !== 'active') return false;
-    if (!attendedRecently(r, { nowMs, unattendedMaxHours })) return true;
-    if (claudeVetoHolds(r, { nowMs, unattendedMaxHours })) return false;
-    const a = effectiveActivityMs(r);
-    return a != null && a <= cutoff;
-  });
-}
-
-// Why the sweep picked a box, for the operator log. Mirrors selectIdleBoxes'
-// branches exactly — if these two ever disagree the log is lying, so they are
-// read together.
-function idleReason(row, { nowMs, idleMinutes, unattendedMaxHours } = {}) {
-  if (!attendedRecently(row, { nowMs, unattendedMaxHours })) {
-    const h = Math.round((nowMs - toMs(row.last_attached_at)) / HOUR_MS);
-    return `unattended ${h}h (cap ${unattendedMaxHours}h) — abandoned session`;
-  }
-  const mins = Math.round((nowMs - (effectiveActivityMs(row) || nowMs)) / 60_000);
-  if (row.claude_active) {
-    const since = toMs(row.claude_active_since);
-    const held = since == null ? 'no claude_active_since recorded' : `claude_active ${Math.round((nowMs - since) / HOUR_MS)}h`;
-    return `idle ${mins}m, ${held} past the ${unattendedMaxHours}h cap`;
-  }
-  return `idle ${mins}m`;
-}
-
-// Dormant = parked boxes that have been parked longer than dormantDays. These
-// get fully de-provisioned (snapshot deleted too) to reclaim the last cents.
-// Since task 1002726 this is the ONLY automated path that destroys a snapshot —
-// the idle sweep parks and preserves one — so it is the last thing standing
-// between a builder and losing uncommitted work. Task 1002727 gates it on a
-// delivered warning.
-function selectDormantBoxes(rows, { dormantDays, nowMs } = {}) {
-  if (!Number.isFinite(dormantDays) || dormantDays <= 0) return [];
-  if (!Number.isFinite(nowMs)) return [];
-  const cutoff = nowMs - dormantDays * 86_400_000;
-  return (rows || []).filter((r) => {
-    if (r.state !== 'parked') return false;
-    const p = toMs(r.parked_at);
-    return p != null && p <= cutoff;
-  });
-}
-
-// Task 1002727 — the WARNING window: parked long enough to be heading for
-// reclaim, but not yet reclaimable. A box here gets one heads-up so its builder
-// can wake it (or accept the loss) before the snapshot goes. Boxes already past
-// dormantDays are excluded — they belong to selectDormantBoxes, which refuses to
-// reclaim an unwarned box. Pure; the caller injects nowMs.
-function selectDormantWarnBoxes(rows, { dormantDays, warnLeadDays, nowMs } = {}) {
-  if (!Number.isFinite(dormantDays) || dormantDays <= 0) return [];
-  if (!Number.isFinite(warnLeadDays) || warnLeadDays <= 0) return [];
-  if (!Number.isFinite(nowMs)) return [];
-  const warnAfter = nowMs - Math.max(dormantDays - warnLeadDays, 0) * 86_400_000;
-  const reclaimAfter = nowMs - dormantDays * 86_400_000;
-  return (rows || []).filter((r) => {
-    if (r.state !== 'parked') return false;
-    const p = toMs(r.parked_at);
-    return p != null && p <= warnAfter && p > reclaimAfter;
-  });
-}
-
-// Task 1002727 — was this box already warned during its CURRENT parked interval?
-// box_events is the state store, so this needs no schema change: a
-// 'dormant_warning' row written at or after parked_at is the receipt. Keying on
-// parked_at (rather than just the newest event) means a wake→park cycle re-arms
-// the warning instead of reusing a stale one from a previous park.
-async function hasDormantWarning(db, { boxId, parkedAt } = {}) {
-  if (!boxId || !parkedAt) return false;
-  const { rows } = await db.query(
-    `SELECT 1 FROM box_events
-      WHERE box_id = $1 AND event = 'dormant_warning' AND created_at >= $2
-      LIMIT 1`,
-    [boxId, parkedAt]
-  );
-  return rows.length > 0;
-}
-
-// ---------------------------------------------------------------------------
-// PURE: state-transition legality
-// ---------------------------------------------------------------------------
-
-// Which lifecycle op is legal from which current state. 'error'/'destroyed' are
-// recoverable into a fresh provision; 'deprovision' is legal from anywhere that
-// holds a droplet or snapshot so an operator can always force-reclaim.
-const TRANSITIONS = {
-  provision: ['none', 'destroyed', 'error'],
-  park: ['active'],
-  wake: ['parked'],
-  deprovision: ['active', 'parking', 'parked', 'waking', 'error'],
-};
-
-function canTransition(op, state) {
-  return (TRANSITIONS[op] || []).includes(state);
-}
-
-// ---------------------------------------------------------------------------
-// PURE: droplet ⇄ box-row drift detection (the reconcile-drift core, task 1289)
-// ---------------------------------------------------------------------------
-
-// States in which a box row legitimately OWNS a running droplet (so its
-// droplet_id should match a real DO droplet). 'parked' is excluded — a parked box
-// has no droplet, only a snapshot. Distinct from SOURCE_HOLDING_STATES (which is
-// about credential issuance, not droplet ownership).
-const DROPLET_HOLDING_STATES = ['active', 'provisioning', 'waking', 'parking'];
-
-// Derive the builder login a fleet droplet belongs to, from its `builder:<login>`
-// tag (how box.js tags every droplet) or, failing that, the `otb-box-<login>`
-// name. Lets the reconcile tear down the matching Cloudflare tunnel + DNS for a
-// zombie. null when neither encodes a login.
-function loginFromDroplet(d) {
-  const tag = (d.tags || []).find((t) => typeof t === 'string' && t.startsWith('builder:'));
-  if (tag) return tag.slice('builder:'.length) || null;
-  const m = /^otb-box-(.+)$/.exec(d.name || '');
-  return (m && m[1]) || null;
-}
-
-// Pure: given the LIVE DigitalOcean droplet list (already filtered to our fleet
-// tag) and the GDS box rows, compute lifecycle drift in BOTH directions — the
-// fix for the task-1289 zombie, where deprovision marked a box 'destroyed' WITHOUT
-// confirming the droplet was deleted, leaving a running droplet no row references.
-//
-//   - zombies: a real droplet that NO box row claims in a droplet-holding state
-//       (the row is destroyed/error/none, or its droplet_id was nulled). It bills,
-//       stays SSH-reachable, and freezes on old code forever → force-delete it.
-//   - ghosts:  a box row in a droplet-holding state whose droplet_id is no longer
-//       present in DO (deleted out-of-band) → mark it 'destroyed' so the DB stops
-//       claiming a running box and the builder can re-provision.
-//
-// In-flight guard: a droplet created seconds ago can belong to a box still in
-// 'provisioning' (the row's droplet_id isn't written until the droplet settles
-// 'active'). Droplets younger than minAgeMinutes are NOT treated as zombies — they
-// are returned under `skippedYoung` so the operator sees them without risk of
-// deleting a provision in progress. Pure + injected (droplets/boxRows/nowMs) so it
-// is unit-tested with no DO, DB, or real clock.
-function planDropletDrift({ droplets = [], boxRows = [], nowMs = null, minAgeMinutes = 30 } = {}) {
-  const liveDropletIds = new Set((droplets || []).map((d) => String(d.id)));
-  const claimedDropletIds = new Set(
-    (boxRows || [])
-      .filter((b) => DROPLET_HOLDING_STATES.includes(b.state) && b.droplet_id != null)
-      .map((b) => String(b.droplet_id))
-  );
-  const builderIdByLogin = new Map(
-    (boxRows || []).filter((b) => b.github_login).map((b) => [b.github_login, b.builder_id])
-  );
-
-  const zombies = [];
-  const skippedYoung = [];
-  for (const d of droplets || []) {
-    if (claimedDropletIds.has(String(d.id))) continue; // a live box owns it — in sync
-    const login = loginFromDroplet(d);
-    const entry = {
-      dropletId: String(d.id), name: d.name || null, login,
-      builderId: login ? (builderIdByLogin.get(login) ?? null) : null,
-      tags: d.tags || [],
-    };
-    const createdMs = toMs(d.created_at);
-    if (Number.isFinite(nowMs) && createdMs != null && (nowMs - createdMs) < minAgeMinutes * 60_000) {
-      skippedYoung.push(entry);
-      continue;
-    }
-    zombies.push(entry);
-  }
-
-  const ghosts = [];
-  for (const b of boxRows || []) {
-    if (!DROPLET_HOLDING_STATES.includes(b.state)) continue;
-    if (b.droplet_id == null) continue;
-    if (liveDropletIds.has(String(b.droplet_id))) continue; // droplet present — in sync
-    ghosts.push({
-      builderId: b.builder_id, login: b.github_login || null,
-      dropletId: String(b.droplet_id), state: b.state,
-    });
-  }
-
-  return { zombies, ghosts, skippedYoung };
-}
-
-// ---------------------------------------------------------------------------
-// PURE: the "make my box ready" decision (#701 box onboarding middleware)
-// ---------------------------------------------------------------------------
-
-// Given a box's current state and the builder's LIVE rank+status, decide what a
-// builder's "I want to connect" request (POST /box/ensure) should do. This is the
-// single decision that delivers BOTH halves of #701's onboarding gap:
-//   - auto-provision   (boxState none/destroyed/error → 'provision')
-//   - wake-on-connect   (boxState parked               → 'wake')
-// plus the no-op / in-flight cases. Pure + tested (tests/boxes.mjs) so the route
-// and any future caller enforce the same rule; the rank gate mirrors
-// box-access.decideSourceAccess (ADR 0016: decided from the live DB rank, which
-// the builder's machine cannot forge). Fail-closed: an unknown rank/state denies.
-//
-// Returns one of:
-//   { action: 'ready' }               box is active — just heartbeat
-//   { action: 'in_progress' }         provision/wake/park already under way
-//   { action: 'provision' }           enqueue a provision intent
-//   { action: 'wake' }                enqueue a wake intent
-//   { action: 'denied', reason, required?, actual? }   not allowed a box
-//
-// `blocked` (migration 104, task 1163): an Archon block bars the two "open"
-// actions — provisioning a NEW box and waking a PARKED one — with the specific,
-// actionable reason BOX_PROVISION_BLOCKED. It is checked PER-BRANCH (not up top)
-// so it does NOT touch an already-active box: blocking is "no new opens" by
-// default, and an active box keeps heartbeating ('ready') until it idles out or
-// is closed. Tearing a running box down at block time is the Archon's separate,
-// explicit choice (PATCH /boxes/:id/block { close_current:true } → deprovision).
-function decideEnsureAction({ boxState, rank, status, blocked = false, floor = DEFAULT_PROVISION_FLOOR } = {}) {
-  // Same gate + order as decideSourceAccess: inactive first, then rank floor.
-  if (status !== 'active') {
-    return { action: 'denied', reason: 'BUILDER_INACTIVE' };
-  }
-  if (!rankMeetsBoxFloor(rank, floor)) {
-    return { action: 'denied', reason: 'INSUFFICIENT_RANK', required: floor, actual: rank ?? null };
-  }
-  switch (boxState) {
-    case 'active':
-      return { action: 'ready' };
-    case 'provisioning':
-    case 'waking':
-    case 'parking':
-      return { action: 'in_progress' };
-    case 'parked':
-      // Waking a parked box is an "open" — a block bars it (a blocked builder
-      // can't resume a box, only keep running one that's already active).
-      if (blocked) return { action: 'denied', reason: 'BOX_PROVISION_BLOCKED' };
-      return { action: 'wake' };
-    case 'none':
-    case 'destroyed':
-    case 'error':
-    case undefined:
-    case null:
-      if (blocked) return { action: 'denied', reason: 'BOX_PROVISION_BLOCKED' };
-      return { action: 'provision' };
-    default:
-      // An unrecognized state is not safe to act on automatically — fail closed
-      // to in_progress so the runner/operator resolves it, never a blind provision.
-      return { action: 'in_progress' };
-  }
-}
-
-// ---------------------------------------------------------------------------
-// DB helpers (async). Each takes the pg pool (or a client mid-transaction).
-// ---------------------------------------------------------------------------
-
-// setBoxWidenPaths — replace a box row's builder-requested widen set (task
-// 1003087). Whole-set replace rather than add/remove SQL: the set is tiny and
-// capped, the caller has already normalized and rank-filtered it, and a
-// read-modify-write in one statement keeps two concurrent widens from
-// interleaving into a half-applied list.
-//
-// Returns the stored array, or null when the builder has no box row — the
-// caller turns that into a 404 rather than silently creating one, because a
-// widen with no box to apply it to is a request that has not happened yet.
-async function setBoxWidenPaths(db, builderId, paths) {
-  const { rows } = await db.query(
-    `UPDATE builder_boxes
-        SET widen_paths = $2::text[], updated_at = now()
-      WHERE builder_id = $1
-      RETURNING widen_paths`,
-    [builderId, Array.isArray(paths) ? paths : []]
-  );
-  return rows[0] ? rows[0].widen_paths : null;
-}
-
-async function getBoxByBuilderId(db, builderId) {
-  const { rows } = await db.query(
-    `SELECT * FROM builder_boxes WHERE builder_id = $1`,
-    [builderId]
-  );
-  return rows[0] || null;
-}
-
-// Ensure a row exists for this builder (state defaults to 'none'); returns it.
-async function ensureBoxRow(db, builderId) {
-  await db.query(
-    `INSERT INTO builder_boxes (builder_id) VALUES ($1)
-       ON CONFLICT (builder_id) DO NOTHING`,
-    [builderId]
-  );
-  return getBoxByBuilderId(db, builderId);
-}
-
-async function listBoxes(db, { state } = {}) {
-  const params = [];
-  let where = '';
-  if (state) { params.push(state); where = `WHERE bb.state = $1`; }
-  const { rows } = await db.query(
-    `SELECT bb.*, b.github_login, b.display_name, b.rank,
-            b.box_blocked, b.box_blocked_reason, b.box_blocked_at
-       FROM builder_boxes bb
-       JOIN builders b ON b.id = bb.builder_id
-       ${where}
-      ORDER BY bb.updated_at DESC
-      LIMIT 1000`,
-    params
-  );
-  return rows;
-}
-
-async function recordEvent(db, { boxId, builderId, event, detail, costUsd, actor }) {
-  await db.query(
-    `INSERT INTO box_events (box_id, builder_id, event, detail, cost_usd, actor)
-     VALUES ($1, $2, $3, $4, $5, $6)`,
-    [boxId, builderId ?? null, event, detail ?? null, costUsd ?? null, actor ?? null]
-  );
-}
-
-// Heartbeat: bump last_activity_at for a builder's ACTIVE box, and optionally
-// record whether a `claude` process is running (claudeActive). Returns the new
-// state (or null if there is no box). A parked/none box is not "kept alive" by
-// a stray heartbeat — only an active box's idle clock resets.
-//
-// Deliberately does NOT write a box_events row: heartbeats fire ~every 5 min per
-// active box, so logging one per beat would grow the ledger unbounded
-// (~100K rows/builder/year). last_activity_at IS the heartbeat record; box_events
-// is reserved for the rare lifecycle transitions (provision/park/wake/deprovision/cost).
-async function bumpActivity(db, builderId, { claudeActive, attached } = {}) {
-  const hasClaude = typeof claudeActive === 'boolean';
-  const claudeCol = hasClaude ? ', claude_active = $2' : '';
-  // The FIRST time a box reports a live `claude` process, stamp
-  // first_connected_at — the write-once, monotonic "this builder has actually
-  // reached a working Claude on their box" signal that clears the onboarding
-  // 'box_connect' step (#823). COALESCE so a later true beat never moves it,
-  // and we only ever set it (never clear it) so a claude_active=false beat
-  // leaves it intact. No new bind param — it reuses now() inline.
-  const connectedCol = (hasClaude && claudeActive === true)
-    ? ', first_connected_at = COALESCE(first_connected_at, now())'
-    : '';
-  // task 1003507 — claude_active_since is the EDGE, not the level: stamped when
-  // the flag goes false->true (COALESCE keeps the original edge across a run of
-  // true beats, so the latch measures the whole session, not the last 5 minutes)
-  // and cleared on a false beat so the next session starts a fresh clock. Without
-  // this the flag has no age, and selectIdleBoxes cannot bound its own veto.
-  const sinceCol = hasClaude
-    ? (claudeActive === true
-      ? ', claude_active_since = COALESCE(claude_active_since, now())'
-      : ', claude_active_since = NULL')
-    : '';
-  // task 1003507 — `attached` is the HUMAN signal (a login session, an inbound
-  // SSH connection, an open browser terminal, or an attached tmux client), kept
-  // separate from claude_active because a running process is not a person. Only
-  // a true beat writes it: last_attached_at is a high-water mark, so a beat that
-  // reports nobody attached leaves the last real attachment where it was and the
-  // unattended clock keeps running. A box whose heartbeat predates this change
-  // never sends the field, leaving the column NULL, which selectIdleBoxes reads
-  // as "no data" rather than "unattended".
-  const attachedCol = attached === true ? ', last_attached_at = now()' : '';
-  const params = hasClaude ? [builderId, claudeActive] : [builderId];
-  const { rows } = await db.query(
-    `UPDATE builder_boxes
-        SET last_activity_at = now(), updated_at = now()${claudeCol}${connectedCol}${sinceCol}${attachedCol}
-      WHERE builder_id = $1 AND state = 'active'
-      RETURNING state`,
-    params
-  );
-  if (rows[0]) return rows[0].state;
-  // No active box: report the current state (if any) without bumping.
-  const cur = await getBoxByBuilderId(db, builderId);
-  return cur ? cur.state : null;
-}
-
-// Has this builder's box EVER reported a live `claude` process? first_connected_at
-// is stamped write-once by bumpActivity (the first claude_active=true heartbeat),
-// so this is the monotonic "properly connected to the dev box" signal that backs
-// the onboarding 'box_connect' step (#823). Cheap boolean; null/absent row → false.
-async function hasEverConnected(db, builderId) {
-  const { rows } = await db.query(
-    `SELECT first_connected_at IS NOT NULL AS connected
-       FROM builder_boxes WHERE builder_id = $1`,
-    [builderId]
-  );
-  return !!(rows[0] && rows[0].connected);
-}
-
-// Columns setBoxState may write. The VALUES are parameterized, but the column
-// NAMES are interpolated into the SQL, so the keys are whitelisted here: an
-// unexpected key (e.g. if a future caller ever wires user-influenced input into
-// the patch) is rejected, not trusted. Closes the latent-injection surface.
-const SETTABLE_BOX_COLUMNS = new Set([
-  'scope', 'provisioned_rank', 'region', 'size_slug', 'droplet_id', 'droplet_name',
-  'snapshot_id', 'ip', 'hostname', 'last_activity_at', 'provisioned_at',
-  'active_since', 'parked_at', 'destroyed_at', 'error_note', 'claude_active',
-  // task 1003507 — park/wake/deprovision clear the claude_active latch and its
-  // clock together. A woken box that kept a stale claude_active_since would be
-  // instantly reapable, which is the fix reintroducing the bug from the far side.
-  'claude_active_since', 'last_attached_at',
-  // host_keys/host_keys_at are normally written by setBoxHostKeys(), but
-  // deprovisionOne() clears them on teardown so a rebuilt box never serves its
-  // predecessor's SSH identity (idea 310) — hence they are settable here too.
-  'host_keys', 'host_keys_at',
-]);
-
-// Generic state-transition writer. `patch` is a column→value map merged into the
-// UPDATE; `updated_at` is always touched. Returns the updated row.
-async function setBoxState(db, builderId, state, patch = {}) {
-  const cols = ['state = $2', 'updated_at = now()'];
-  const params = [builderId, state];
-  let i = 3;
-  for (const [k, v] of Object.entries(patch)) {
-    if (!SETTABLE_BOX_COLUMNS.has(k)) {
-      throw new Error(`setBoxState: refusing to write non-allowlisted column '${k}'`);
-    }
-    cols.push(`${k} = $${i}`);
-    params.push(v);
-    i++;
-  }
-  const { rows } = await db.query(
-    `UPDATE builder_boxes SET ${cols.join(', ')} WHERE builder_id = $1 RETURNING *`,
-    params
-  );
-  return rows[0] || null;
-}
-
-// Accrue compute cost for a box: add to its running tally, append a 'cost'
-// event, AND mirror to cost_log (category 'compute', builder-attributed) so the
-// public status dashboard's by_builder split sees it. Called at park/deprovision.
-async function recordComputeCost(db, { box, untilMs, actor }) {
-  const cost = computeActiveCostUsd({
-    sizeSlug: box.size_slug,
-    activeSinceMs: toMs(box.active_since),
-    untilMs,
-  });
-  if (cost <= 0) return 0;
-  await db.query(
-    `UPDATE builder_boxes
-        SET compute_cost_usd = compute_cost_usd + $2, updated_at = now()
-      WHERE id = $1`,
-    [box.id, cost]
-  );
-  await recordEvent(db, {
-    boxId: box.id, builderId: box.builder_id, event: 'cost', costUsd: cost,
-    detail: `${box.size_slug} active ${(((untilMs - toMs(box.active_since)) / 3_600_000) || 0).toFixed(2)}h`,
-    actor,
-  });
-  // source_ref is unique PER ACCRUAL INTERVAL (box id + the interval's end ms),
-  // not just per box — a box is parked/woken many times, each a distinct compute
-  // interval. The cost_log UNIQUE(source, source_ref) (migration 004) would
-  // otherwise collide on the second park and crash it. Keying on untilMs keeps
-  // idempotency where it matters: replaying the EXACT same accrual de-dupes
-  // (ON CONFLICT DO NOTHING) rather than double-charging.
-  await db.query(
-    `INSERT INTO cost_log (amount_usd, category, description, source, source_ref, builder_id)
-     VALUES ($1, 'compute', $2, 'box-lifecycle', $3, $4)
-     ON CONFLICT DO NOTHING`,
-    [
-      cost,
-      `Dev box compute (${box.size_slug})`,
-      `builder_boxes#${box.id}@${untilMs}`,
-      box.builder_id,
-    ]
-  );
-  return cost;
-}
-
-// Log a spin-up LEDGER EVENT each time a box is created (provision) or resumed
-// (wake). Mirrors recordComputeCost but ALWAYS writes the row (even at $0) — the
-// point is a timestamped "box came up" line in the per-builder ledger, not a
-// charge. Idempotent per (box, kind, atMs) via the unique cost_log source_ref.
-async function recordSpinupCost(db, { box, kind = 'provision', atMs, actor }) {
-  const cost = SPINUP_COST_USD;
-  if (cost > 0) {
-    await db.query(
-      `UPDATE builder_boxes SET compute_cost_usd = compute_cost_usd + $2, updated_at = now() WHERE id = $1`,
-      [box.id, cost]
-    );
-  }
-  await recordEvent(db, {
-    boxId: box.id, builderId: box.builder_id, event: 'cost', costUsd: cost,
-    detail: `Dev box spin-up (${kind})`, actor,
-  });
-  await db.query(
-    `INSERT INTO cost_log (amount_usd, category, description, source, source_ref, builder_id)
-     VALUES ($1, 'compute', $2, 'box-spinup', $3, $4)
-     ON CONFLICT DO NOTHING`,
-    [cost, `Dev box spin-up (${kind})`, `builder_boxes#${box.id}:spinup:${kind}@${atMs}`, box.builder_id]
-  );
-  return cost;
-}
-
-// Accrue STORAGE cost for a box that spent time parked (snapshot retained). The
-// running-box disk is already in compute; this is the snapshot-only line. Called
-// at deprovision when the box has a parked_at. No-op for a never-parked box.
-async function recordStorageCost(db, { box, untilMs, actor }) {
-  const parkedSinceMs = toMs(box.parked_at);
-  const cost = storageCostUsd({ parkedSinceMs, untilMs });
-  if (cost <= 0) return 0;
-  await db.query(
-    `UPDATE builder_boxes SET compute_cost_usd = compute_cost_usd + $2, updated_at = now() WHERE id = $1`,
-    [box.id, cost]
-  );
-  await recordEvent(db, {
-    boxId: box.id, builderId: box.builder_id, event: 'cost', costUsd: cost,
-    detail: `Dev box storage (snapshot) ${(((untilMs - parkedSinceMs) / 3_600_000) || 0).toFixed(2)}h`,
-    actor,
-  });
-  await db.query(
-    `INSERT INTO cost_log (amount_usd, category, description, source, source_ref, builder_id)
-     VALUES ($1, 'compute', $2, 'box-storage', $3, $4)
-     ON CONFLICT DO NOTHING`,
-    [cost, 'Dev box storage (snapshot)', `builder_boxes#${box.id}:storage@${untilMs}`, box.builder_id]
-  );
-  return cost;
-}
-
-// The caller's own container-cost summary (#602): bucket their box-* cost_log
-// rows into { spinup_usd, compute_usd, storage_usd, total_usd } so a builder sees
-// what their dev box would cost. Own-scoped — callers pass req.builder.id.
-async function boxCostSummaryForBuilder(db, builderId) {
-  const { rows } = await db.query(
-    `SELECT amount_usd, source FROM cost_log
-      WHERE builder_id = $1 AND source = ANY($2)`,
-    [builderId, BOX_COST_SOURCES]
-  );
-  return summarizeBoxCost(rows);
-}
-
-// The full container-cost ledger for Archon oversight (#602): every box-* cost
-// row (newest first) joined to the builder, plus per-builder totals — so an
-// Archon sees all box spend without a DB query. limit caps the row list.
-async function boxCostLedger(db, { limit = 500 } = {}) {
-  const { rows: ledger } = await db.query(
-    `SELECT c.recorded_at, c.amount_usd, c.source, c.description, c.builder_id,
-            b.github_login AS builder_login
-       FROM cost_log c LEFT JOIN builders b ON b.id = c.builder_id
-      WHERE c.source = ANY($1)
-      ORDER BY c.recorded_at DESC
-      LIMIT $2`,
-    [BOX_COST_SOURCES, limit]
-  );
-  const { rows: totalsRows } = await db.query(
-    `SELECT c.builder_id, b.github_login AS builder_login,
-            SUM(c.amount_usd)::numeric(12,4) AS total_usd
-       FROM cost_log c LEFT JOIN builders b ON b.id = c.builder_id
-      WHERE c.source = ANY($1)
-      GROUP BY c.builder_id, b.github_login
-      ORDER BY total_usd DESC`,
-    [BOX_COST_SOURCES]
-  );
-  return { ledger, totals_by_builder: totalsRows };
-}
-
-// ---------------------------------------------------------------------------
-// DB helpers — the #701 intent queue + #760 terminal-access store
-// ---------------------------------------------------------------------------
-
-// Enqueue a provision/wake intent for a builder. At most ONE open intent per
-// builder (the ux_box_intents_open partial unique index) — a second concurrent
-// enqueue collides and we return the ALREADY-OPEN intent instead of piling up.
-// Returns { intent, created }: created=false means an open intent already
-// existed (the route reports it rather than queuing a duplicate).
-//
-// The row always inserts state='pending' — the runner drains it on its next tick.
-async function enqueueIntent(db, builderId, action, requestedBy) {
-  try {
-    const { rows } = await db.query(
-      `INSERT INTO box_intents (builder_id, action, requested_by, state)
-       VALUES ($1, $2, $3, 'pending') RETURNING *`,
-      [builderId, action, requestedBy ?? null]
-    );
-    return { intent: rows[0], created: true };
-  } catch (e) {
-    // 23505 = unique_violation on ux_box_intents_open: an open intent exists.
-    if (e && e.code === '23505') {
-      const existing = await getOpenIntent(db, builderId);
-      if (existing) return { intent: existing, created: false };
-    }
-    throw e;
-  }
-}
-
-// The builder's currently-open (pending|running) intent, if any.
-async function getOpenIntent(db, builderId) {
-  const { rows } = await db.query(
-    `SELECT * FROM box_intents
-      WHERE builder_id = $1 AND state IN ('pending', 'running')
-      ORDER BY created_at DESC LIMIT 1`,
-    [builderId]
-  );
-  return rows[0] || null;
-}
-
-// Atomically claim the oldest pending intent for the runner: flip it to
-// 'running', bump attempts. FOR UPDATE SKIP LOCKED so concurrent runner ticks
-// (or an overlapping run) never grab the same row. Returns the claimed row or null.
-async function claimNextIntent(db) {
-  const { rows } = await db.query(
-    `UPDATE box_intents
-        SET state = 'running', attempts = attempts + 1, updated_at = now()
-      WHERE id = (
-        SELECT id FROM box_intents
-         WHERE state = 'pending'
-         ORDER BY created_at
-         FOR UPDATE SKIP LOCKED
-         LIMIT 1
-      )
-      RETURNING *`
-  );
-  return rows[0] || null;
-}
-
-// Resolve a claimed intent to its terminal state ('done' | 'error').
-async function resolveIntent(db, id, state, lastError) {
-  await db.query(
-    `UPDATE box_intents
-        SET state = $2, last_error = $3, updated_at = now(), resolved_at = now()
-      WHERE id = $1`,
-    [id, state, lastError ?? null]
-  );
-}
-
-// Record the web-terminal access a box published (POST /box/terminal, ADR 0038).
-// `url` is the box's current Cloudflare-Tunnel terminal URL; `credential` is its
-// per-box basic-auth password (user:pass behind the URL). BOTH are stored only
-// for an ACTIVE box — they are meaningless for a parked/none box, and storing
-// them would let a stale URL/credential be served after a park. Returns the
-// updated state (or null if there is no box). Mirrors the migration-070 staleness
-// model: the read side (GET /box/terminal) also gates on state='active'.
-async function setTerminalAccess(db, builderId, { url, credential }) {
-  const { rows } = await db.query(
-    `UPDATE builder_boxes
-        SET terminal_url = $2, terminal_credential = $3, terminal_at = now(), updated_at = now()
-      WHERE builder_id = $1 AND state = 'active'
-      RETURNING state`,
-    [builderId, url, credential || null]
-  );
-  if (rows[0]) return rows[0].state;
-  const cur = await getBoxByBuilderId(db, builderId);
-  return cur ? cur.state : null;
-}
-
-// Record the SSH HOST PUBLIC keys a box reported (POST /box/host-keys — task 1187 /
-// idea 235). `hostKeys` is newline-joined bare `<keytype> <base64>` pairs, already
-// validated + normalized by box-onboard.validateHostKeyLines (no hostname prefix, no
-// comment). Stored ONLY for an ACTIVE box, mirroring setTerminalAccess: a parked/none
-// box's host identity is meaningless to pin, and the value persists across a snapshot
-// wake anyway (so no NULL-clear on park). Returns the updated state, or the current
-// state if there is no active row to write. PUBLIC keys only — never the private half.
-async function setBoxHostKeys(db, builderId, { hostKeys }) {
-  const { rows } = await db.query(
-    `UPDATE builder_boxes
-        SET host_keys = $2, host_keys_at = now(), updated_at = now()
-      WHERE builder_id = $1 AND state = 'active'
-      RETURNING state`,
-    [builderId, hostKeys || null]
-  );
-  if (rows[0]) return rows[0].state;
-  const cur = await getBoxByBuilderId(db, builderId);
-  return cur ? cur.state : null;
-}
-
-// --- box code-version reporting (idea 332 / task 1316, ADR 0072) -------------
-//
-// A box reports its /workspace HEAD commit so the server can flag "running old
-// code". WRITTEN only when state='active' (same gate as setBoxHostKeys) — we
-// don't record a version for a box we're not serving.
-async function setBoxCodeVersion(db, builderId, { sha, committedAt }) {
-  const { rows } = await db.query(
-    `UPDATE builder_boxes
-        SET code_sha = $2, code_committed_at = $3, code_reported_at = now(), updated_at = now()
-      WHERE builder_id = $1 AND state = 'active'
-      RETURNING state`,
-    [builderId, sha || null, committedAt || null]
-  );
-  if (rows[0]) return rows[0].state;
-  const cur = await getBoxByBuilderId(db, builderId);
-  return cur ? cur.state : null;
-}
-
-// A fresh box reports its version within ~10 min (the box-source-fetch cron tick).
-// Give a generous grace so a just-provisioned box that hasn't reported YET isn't
-// flagged, and a generous commit-date lag so a box mid-pull right after a deploy
-// isn't flagged — the target is WEEKS-stale boxes, not minutes-behind ones.
-const CODE_REPORT_GRACE_MS = 30 * 60 * 1000;       // 30 min after provision
-const CODE_STALE_LAG_MS = 2 * 24 * 60 * 60 * 1000; // 2 days behind deployed code
-
-// Pure: decide whether a box is running stale code. Inputs accept Date | ISO
-// string | epoch-ms (pg hands us Dates; tests pass either). Returns
-// { stale, reason } where reason ∈
-//   not_active            — only active boxes are judged (parked/destroyed → n/a)
-//   awaiting_first_report — active, never reported, still inside provision grace
-//   never_reported        — active, past grace, never reported ⇒ NOT stale. Silence
-//                           is an unknown, not a verdict: it means the reporter never
-//                           ran, which is at least as likely to be OUR fault as the
-//                           box's. It was our fault for the whole life of this feature
-//                           (task 1002698) — ADR 0072 specified infra/box-report-version.sh
-//                           and it was never written (task 1002699), so EVERY box in the
-//                           fleet read as stale, and the banner's only remedy (destroy the
-//                           box, provision a fresh one) could not possibly clear it. A
-//                           builder who believed it rebuilt in a loop, losing uncommitted
-//                           work and spending money each time. Only a box that has ACTUALLY
-//                           REPORTED can be called stale — see 'behind'.
-//   behind                — reported, but its commit is > CODE_STALE_LAG_MS older
-//                           than the server's deployed commit ⇒ STALE (a box whose
-//                           `pull --ff-only` has been silently failing)
-//   current               — reported and within the lag window
-//   unknown               — reported, but we can't compare (no commit dates) ⇒ not stale
-function computeCodeStaleness({ state, provisionedAt, codeReportedAt, codeCommittedAt, serverCommittedAt, now = Date.now() } = {}) {
-  const toMs = (x) => {
-    if (x == null) return null;
-    const t = x instanceof Date ? x.getTime() : new Date(x).getTime();
-    return Number.isFinite(t) ? t : null;
-  };
-  if (state !== 'active') return { stale: false, reason: 'not_active' };
-
-  const reported = toMs(codeReportedAt);
-  if (reported == null) {
-    const prov = toMs(provisionedAt);
-    const withinGrace = prov != null && (now - prov) < CODE_REPORT_GRACE_MS;
-    if (withinGrace) return { stale: false, reason: 'awaiting_first_report' };
-    // Not stale — see the 'never_reported' note above. The reason is still returned
-    // so an operator surface can show "we don't know", which is the honest answer.
-    return { stale: false, reason: 'never_reported' };
-  }
-
-  const boxCommit = toMs(codeCommittedAt);
-  const srvCommit = toMs(serverCommittedAt);
-  if (boxCommit == null || srvCommit == null) return { stale: false, reason: 'unknown' };
-  const lagMs = srvCommit - boxCommit;
-  if (lagMs > CODE_STALE_LAG_MS) return { stale: true, reason: 'behind', lag_ms: lagMs };
-  return { stale: false, reason: 'current' };
-}
-
-// PURE: are the box's REPORTED SSH host keys older than the droplet now running?
-// A rebuild mints fresh host keys, and until the new box re-reports (~10 min) the
-// row can still carry its predecessor's identity — pinning that is the "Host denied
-// (verification failed)" lockout. A report that predates `active_since` therefore
-// describes a droplet that no longer exists; so does a missing timestamp on either
-// side. Callers must fall back to a live keyscan rather than pin a dead identity.
-function hostKeysAreStale({ hostKeysAt, activeSince } = {}) {
-  const toMs = (x) => {
-    if (x == null) return null;
-    const t = x instanceof Date ? x.getTime() : new Date(x).getTime();
-    return Number.isFinite(t) ? t : null;
-  };
-  const reported = toMs(hostKeysAt);
-  const activated = toMs(activeSince);
-  if (reported == null || activated == null) return true;
-  return reported < activated;
-}
-
-module.exports = {
-  // pure — rank
-  RANK_ORDER,
-  DEFAULT_PROVISION_FLOOR,
-  rankMeetsBoxFloor,
-  boxScopeForRank,
-  assertProvisionAllowed,
-  // pure — size/cost
-  SIZE_CATALOG,
-  DEFAULT_SIZE,
-  sizeHourlyUsd,
-  computeActiveCostUsd,
-  // pure — container cost ledger (#602)
-  SPINUP_COST_USD,
-  SNAPSHOT_MONTHLY_USD,
-  BOX_COST_SOURCES,
-  storageCostUsd,
-  summarizeBoxCost,
-  // pure — selection
-  attendedRecently,
-  claudeVetoHolds,
-  effectiveActivityMs,
-  idleReason,
-  selectIdleBoxes,
-  selectDormantBoxes,
-  selectDormantWarnBoxes,
-  hasDormantWarning,
-  // pure — transitions
-  TRANSITIONS,
-  canTransition,
-  // pure — code staleness (idea 332 / task 1316)
-  computeCodeStaleness,
-  CODE_REPORT_GRACE_MS,
-  CODE_STALE_LAG_MS,
-  // pure — host-key staleness (task 1002509)
-  hostKeysAreStale,
-  // pure — droplet⇄row drift (task 1289)
-  DROPLET_HOLDING_STATES,
-  loginFromDroplet,
-  planDropletDrift,
-  // pure — ensure (#701)
-  decideEnsureAction,
-  // db
-  getBoxByBuilderId,
-  setBoxWidenPaths,
-  ensureBoxRow,
-  listBoxes,
-  recordEvent,
-  bumpActivity,
-  hasEverConnected,
-  setBoxState,
-  setBoxCodeVersion,
-  recordComputeCost,
-  recordSpinupCost,
-  recordStorageCost,
-  boxCostSummaryForBuilder,
-  boxCostLedger,
-  // db — intent queue (#701) + terminal access (#760)
-  enqueueIntent,
-  getOpenIntent,
-  claimNextIntent,
-  resolveIntent,
-  setTerminalAccess,
-  setBoxHostKeys,
-};