@bongos/core 1.17.0

package/modules/dev-box/boxes.js

@@ -0,0 +1,842 @@
+// 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);
+}
+
+// Idle = active boxes whose effective activity is older than idleMinutes AND
+// that don't have an active Claude process. A box with claude_active=true is
+// kept alive regardless of last_activity_at — the session ends when Claude stops.
+// Pure: caller passes the candidate rows and nowMs; returns the subset to deprovision.
+function selectIdleBoxes(rows, { idleMinutes, nowMs } = {}) {
+  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 (r.claude_active) return false;
+    const a = effectiveActivityMs(r);
+    return a != null && a <= cutoff;
+  });
+}
+
+// Dormant = parked boxes that have been parked longer than dormantDays. These
+// get fully de-provisioned (snapshot deleted too) to reclaim the last cents.
+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;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// 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).
+// ---------------------------------------------------------------------------
+
+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 } = {}) {
+  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())'
+    : '';
+  const params = hasClaude ? [builderId, claudeActive] : [builderId];
+  const { rows } = await db.query(
+    `UPDATE builder_boxes
+        SET last_activity_at = now(), updated_at = now()${claudeCol}${connectedCol}
+      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',
+  // 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 ⇒ too old to even
+//                           run the reporter (a pre-self-update box) ⇒ STALE
+//   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' };
+    return { stale: true, 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' };
+}
+
+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
+  effectiveActivityMs,
+  selectIdleBoxes,
+  selectDormantBoxes,
+  // pure — transitions
+  TRANSITIONS,
+  canTransition,
+  // pure — code staleness (idea 332 / task 1316)
+  computeCodeStaleness,
+  CODE_REPORT_GRACE_MS,
+  CODE_STALE_LAG_MS,
+  // pure — droplet⇄row drift (task 1289)
+  DROPLET_HOLDING_STATES,
+  loginFromDroplet,
+  planDropletDrift,
+  // pure — ensure (#701)
+  decideEnsureAction,
+  // db
+  getBoxByBuilderId,
+  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,
+};