@bongos/core 1.19.1072 → 1.19.1074

package/modules/dev-box/routes/box.js

@@ -1,1223 +0,0 @@
-// src/bongos/routes/box.js — read + heartbeat surface for the per-builder dev box
-// lifecycle (ADR 0031 §2/§5, #598).
-//
-// The web Node process NEVER shells out to the DigitalOcean API — a stolen
-// builder token can never directly spin up or destroy infrastructure. The
-// real-money lifecycle is split: web routes only ENQUEUE an intent (provision /
-// wake / deprovision) into box_intents, and the control-plane runner
-// (scripts/gds/box.js) is the sole holder of DO_API_TOKEN that executes them
-// (ADR 0031 §9.4). This router carries the read surface + the intent-enqueueing
-// mutations:
-//
-//   GET   /box/me                  — the caller's own box state/IP/cost  (any builder; own)
-//   POST  /box/heartbeat           — bump the caller's own activity clock (any builder; own)
-//   POST  /box/close               — enqueue deprovision of the caller's own box (own)
-//   GET   /boxes                   — the full box roster                  (Archon)
-//   POST  /boxes/:id/close         — enqueue deprovision of ANY box       (Archon; idea 257)
-//   PATCH /boxes/:id/block         — bar/un-bar a builder from opening boxes (Archon; idea 257)
-//
-// The heartbeat is what feeds the idle sweep: the box pings while a builder is
-// working, resetting its idle clock; silence past BOX_IDLE_MINUTES lets the
-// sweep park it (snapshot + destroy → compute billing stops).
-
-const fs = require('node:fs');
-const path = require('node:path');
-const express = require('express');
-// The kernel doorway (ADR 0083 / BV1.R37): this module reaches core ONLY through
-// module-api — never a core internal directly. `auth`/`gdsDb` are aliased to the
-// doorway so the existing auth.*/gdsDb.* call sites read unchanged.
-const api = require('../../../src/module-api');
-const auth = api;
-const gdsDb = api;
-const { pool, buildInfo, validateOrRespond, LIMITS } = api;
-// Box-internal modules (same module → same-dir relative requires).
-const boxes = require('../boxes');
-const boxAccess = require('../box-access');
-const boxCredential = require('../box-credential');
-const boxOnboard = require('../box-onboard');
-// This module's own data slice (BV1.R68 / ADR 0091) — owns the box-domain
-// queries lifted out of core db.js. Kernel reads (getBuilderById) still come
-// from the doorway via `gdsDb`.
-const db = require('../db');
-// task 1003208: structured logging (pino via the doorway) — was console.*.
-const log = api.logger('dev-box');
-
-// Repo root, for serving the (non-secret) bootstrap scripts that live in infra/.
-const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
-
-// The FIXED public origin baked into the served connect scripts + guide. It is
-// DELIBERATELY NOT derived from the request (publicOrigin / X-Forwarded-Host):
-// these scripts are run as `curl … | bash` and then carry a GitHub/GDS bearer
-// token, so a spoofable Host header in the served GDS_API_BASE would let an
-// attacker redirect a victim's bootstrap at their own server (token theft + RCE
-// on the laptop). Same posture + env var the OAuth redirect_uri uses (auth.js
-// DISCORD_REDIRECT_ORIGIN). Staging sets <PREFIX>_PUBLIC_ORIGIN in its env —
-// resolved through the doorway's resolveEnv so the deployed GDS_PUBLIC_ORIGIN
-// still wins over the branding default until the sunset (task 1003703).
-const PUBLIC_ORIGIN = api.resolveEnv('PUBLIC_ORIGIN')
-  || (() => { try { return api.branding().domains.publicOrigin; } catch { return 'http://localhost:3000'; } })();
-
-// Task-scoping PAUSE (task 1003285 / ADR 0193 — owner decision, 2026-08-25).
-// While paused, the claim-derived slice is never resolved: scopeKeys stays
-// undefined and decideSourceAccess takes its documented rank fallback — full
-// repo for Metic+, the starter surface below. Rank floor, ADR 0016 live-rank
-// checks, and the ADR 0055 read-only credential are all unchanged; only the
-// module BREADTH stops narrowing. Paused by default; set BOX_TASK_SCOPE=on
-// to re-enable the ADR 0148 claim-driven slice.
-function taskScopingPaused() {
-  return String(process.env.BOX_TASK_SCOPE || '').trim().toLowerCase() !== 'on';
-}
-
-// The instance's world name + dev-box apex + SSH zone come from the branding pack
-// (ADR 0062 §3), never a hardcoded host brand — a non-OTB instance uses its own
-// configured identity/domains. Passed into the PURE box-onboard renderers.
-function devBoxApex() { try { return api.branding().domains.devBoxBase || ''; } catch { return ''; } }
-function devBoxWorld() { try { return api.branding().identity.worldName || 'the platform'; } catch { return 'the platform'; } }
-
-// The per-builder box DNS zone (mirrors scripts/gds/box.js CONFIG.dnsZone). The
-// hostname is deterministic from the login, so managed-settings can be issued
-// BEFORE the box is provisioned (the builder places it, then connects once the
-// operator provisions). Kept here so the route and the CLI derive the same name.
-function boxDnsZone() {
-  if (process.env.BOX_DNS_ZONE) return process.env.BOX_DNS_ZONE;
-  try { return api.branding().domains.sshBoxBase || ''; } catch { return ''; }
-}
-function hostnameForLogin(login) { return `box-${login}.${boxDnsZone()}`; }
-
-// The provisioning rank floor (#701 /box/ensure), mirroring scripts/gds/box.js
-// CONFIG.floor and boxes.DEFAULT_PROVISION_FLOOR. Kept here so the route's
-// auto-provision gate uses the SAME floor the control-plane CLI does.
-function provisionFloor() { return process.env.BOX_PROVISION_MIN_RANK || 'xenos'; }
-
-// SECURITY (#871): SSRF allow-list for the box web-terminal URL. POST /box/terminal
-// stores a builder-supplied URL and GET /box/terminal makes the WEB TIER fetch it
-// (a reachability probe). The old guard (/^https:\/\/[^\s]+$/) accepted ANY https
-// host — including 127.0.0.1, 10.x/192.168/172.16, 169.254.169.254 (cloud
-// metadata), [::1], *.local/*.internal — so a builder could make the prod server
-// probe arbitrary internal endpoints. A legitimate terminal URL is ALWAYS one of
-// exactly two shapes (see cf-tunnel.js terminalHostname + the quick-tunnel
-// default): the named tunnel `term-<login>.<zone>` under example.com, or a
-// Cloudflare quick tunnel `*.trycloudflare.com`. We bind the named form to the
-// CALLER's own login so one builder can't even name another's terminal host.
-// PURE + exported for unit tests (no network, no DB).
-function isSafeTerminalUrl(rawUrl, login, apex = devBoxApex()) {
-  let u;
-  try { u = new URL(String(rawUrl || '')); } catch { return false; }
-  if (u.protocol !== 'https:') return false;
-  // Reject anything with embedded credentials (user:pass@host).
-  if (u.username || u.password) return false;
-  const host = u.hostname.toLowerCase();
-  if (!host) return false;
-  // Reject IP literals (the only way to hit metadata/loopback/private ranges by
-  // address) — IPv4 dotted-quad and IPv6 (URL hostname strips the [] brackets,
-  // leaving colons, so a ':' in the host means an IPv6 literal).
-  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host)) return false;
-  if (host.includes(':')) return false;
-  // Reject loopback / internal-zone names.
-  if (host === 'localhost' || host.endsWith('.localhost') ||
-      host.endsWith('.local') || host.endsWith('.internal')) return false;
-  // Allow ONLY the two legitimate tunnel shapes.
-  if (host.endsWith('.trycloudflare.com')) return true;
-  const safeLogin = String(login || '').toLowerCase();
-  if (safeLogin && apex && host.startsWith(`term-${safeLogin}.`) && host.endsWith('.' + apex)) {
-    return true;
-  }
-  return false;
-}
-
-// (#889) Is an HTTP status from probing the terminal URL a sign the tunnel is
-// actually serving? The URL is recorded at provision time, BEFORE cloudflared
-// connects, so a probe is the only way to tell "live" from "still booting".
-// Cloudflare's edge answers even when the tunnel is DOWN — error 1033 is served
-// as HTTP 530, and origin-unreachable as 502/503/504/52x — so "any HTTP
-// response = ready" handed out a clickable link that 1033s (builder 25). The
-// tunnel is ready ONLY when the ORIGIN answered: ttyd behind basic-auth returns
-// 401 (or 2xx/3xx once authed). Every 5xx (incl. 530) means not-yet-ready.
-// PURE + exported for unit tests.
-function isTunnelReadyStatus(status) {
-  return status === 401 || (status >= 200 && status < 400);
-}
-
-// Read one of the infra bootstrap scripts and bake the server's PINNED public
-// origin (PUBLIC_ORIGIN / GDS_PUBLIC_ORIGIN) in as GDS_API_BASE. apiBase is that
-// constant, NEVER a request header — do NOT change this to a request-derived
-// origin: it would reintroduce the spoofable-Host token-theft/RCE blocker (the
-// served script is run as `curl … | bash` and then carries a bearer token).
-// Staging targets staging by setting GDS_PUBLIC_ORIGIN in its env. Returns null
-// if the file is missing (the route then 404s rather than serving junk).
-function readBootstrapScript(name, apiBase) {
-  try {
-    const raw = fs.readFileSync(path.join(REPO_ROOT, 'infra', name), 'utf8');
-    return raw.split('__GDS_API_BASE__').join(apiBase);
-  } catch {
-    return null;
-  }
-}
-
-// What we surface for a box — never the raw DO token or anything secret; the
-// row holds none, but we still project an explicit allow-list.
-function publicBox(row) {
-  if (!row) return { state: 'none' };
-  return {
-    state: row.state,
-    scope: row.scope,
-    region: row.region,
-    size_slug: row.size_slug,
-    ip: row.ip,
-    hostname: row.hostname,
-    last_activity_at: row.last_activity_at,
-    provisioned_at: row.provisioned_at,
-    // When the CURRENT droplet came up. provisioned_at is preserved across rebuilds,
-    // so this is the only timestamp a client can compare host_keys_at against to
-    // tell a fresh identity report from a dead box's (boxes.hostKeysAreStale).
-    active_since: row.active_since || null,
-    parked_at: row.parked_at,
-    compute_cost_usd: Number(row.compute_cost_usd || 0),
-    claude_active: row.claude_active ?? false,
-    // task 1187 / idea 235: the box's PUBLIC SSH host keys (newline-joined
-    // `<keytype> <base64>`), reported by the box. The connect path writes them to
-    // known_hosts authoritatively. Public, own-scoped (GET /box/me) — not a secret.
-    host_keys: row.host_keys || null,
-    host_keys_at: row.host_keys_at || null,
-    // idea 332 / task 1316 (ADR 0072): code-staleness, so the hall/app can flag
-    // "this box is running old code — rebuild." The box reports its /workspace
-    // HEAD (POST /box/version); the server compares it to its OWN deployed commit
-    // date (buildInfo().commitDate). Computed here so /box/me + /boxes share it.
-    code: {
-      sha: row.code_sha || null,
-      committed_at: row.code_committed_at || null,
-      reported_at: row.code_reported_at || null,
-      ...boxes.computeCodeStaleness({
-        state: row.state,
-        provisionedAt: row.provisioned_at,
-        codeReportedAt: row.code_reported_at,
-        codeCommittedAt: row.code_committed_at,
-        serverCommittedAt: buildInfo().commitDate,
-      }),
-    },
-  };
-}
-
-// Register this module's kernel seams (ADR 0083 / BV1.R43). Idempotent — the loader
-// calls this factory once at boot, but tests may instantiate the router repeatedly;
-// gating on hasProvider keeps the port single-registered and the reconcile listener
-// single-wired (both re-register together after a seam _reset()).
-//   • PROVIDES port `box.hasEverConnected` — the box-connection signal core
-//     onboarding (GET /me, GET /builders/:id/onboarding) reads via resolveOptional.
-//   • LISTENS  event `builder.box-reconcile-needed` — emitted by core db.js after a
-//     rank/status change; flags the droplet reconcile (replaces the old
-//     core db.js → box-access direct import).
-function registerBoxSeams() {
-  if (api.hasProvider('box.hasEverConnected')) return;
-  api.registerProvider('box.hasEverConnected', (builderId) => boxes.hasEverConnected(pool, builderId));
-  api.on('builder.box-reconcile-needed', async ({ builderId, rank, status, actor }) => {
-    await boxAccess.flagBoxReconcileForBuilder(pool, builderId, { rank, status, actor });
-  });
-}
-
-module.exports = function buildBoxRouter() {
-  registerBoxSeams();
-  const router = express.Router();
-
-  // Route ORDER is deliberate: the Archon-gated route is declared FIRST, then
-  // the any-builder routes. The route-rank auditor (src/bongos/route-rank-check.js)
-  // classifies a route from a 20-line lookahead window, checking requireRank
-  // before requireBuilder. With compact handlers like these, putting an
-  // archon route BELOW an any-builder one would bleed its `requireRank('archon')`
-  // up into the any-builder route's window and mislabel it. Archon-first keeps
-  // every route classifying to its true gate (verified in the ship pre-pass).
-
-  // GET /boxes — full roster across all builders. rank: archon (exposes every
-  // builder's box + IP + cost; same gate as the rest of roster management).
-  router.get('/boxes', auth.requireBuilder, auth.requirePermission('box.fleet.manage'), async (req, res) => {
-    try {
-      const state = req.query.state || undefined;
-      const rows = await boxes.listBoxes(pool, { state });
-      res.json({
-        boxes: rows.map((r) => ({
-          builder: {
-            id: r.builder_id,
-            github_login: r.github_login,
-            display_name: r.display_name,
-            rank: r.rank,
-          },
-          ...publicBox(r),
-          // idea 257 / task 1163: surface the provisioning block so the Harbor
-          // shows who is barred (incl. blocked builders with no live box — they
-          // carry a state='none' row created at block time).
-          blocked: {
-            is: !!r.box_blocked,
-            reason: r.box_blocked_reason || null,
-            at: r.box_blocked_at || null,
-          },
-          droplet_id: r.droplet_id,
-          snapshot_id: r.snapshot_id,
-        })),
-      });
-    } catch (err) {
-      log.error('[gds] GET /boxes', err);
-      res.fail('roster_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // GET /boxes/cost-ledger — the full per-builder container-cost ledger + totals
-  // (#602). rank: archon — cost oversight across every builder without a DB query.
-  // Declared among the archon routes (archon-first) so the route-rank auditor's
-  // 20-line lookahead classifies it correctly.
-  router.get('/boxes/cost-ledger', auth.requireBuilder, auth.requirePermission('box.fleet.manage'), async (req, res) => {
-    try {
-      // R14 (#2001 / ADR 0119): shared helper; per-endpoint cap preserved (default 500, max 2000).
-      const { limit } = api.parsePagination(req, { defaultLimit: 500, maxLimit: 2000 });
-      const out = await boxes.boxCostLedger(pool, { limit });
-      res.json(out);
-    } catch (err) {
-      log.error('[gds] GET /boxes/cost-ledger', err);
-      res.fail('cost_ledger_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // POST /boxes/:builderId/close — Archon force-closes ANY builder's box (idea
-  // 257 / task 1163). Trust-safe by the same mechanism as the builder's own
-  // POST /box/close: it ENQUEUES a 'deprovision' intent and the control-plane
-  // runner executes it, so the web tier never holds DO_API_TOKEN (ADR 0031
-  // §9.4). rank: archon (acts on another builder's paid infrastructure).
-  // Declared among the archon routes (archon-first) so the route-rank auditor's
-  // 20-line lookahead classifies it correctly.
-  router.post('/boxes/:builderId/close', auth.requireBuilder, auth.requirePermission('box.fleet.manage'), async (req, res) => {
-    const builderId = Number(req.params.builderId);
-    if (!Number.isInteger(builderId) || builderId < 1) {
-      return res.fail('bad_builder_id', 400);
-    }
-    try {
-      const box = await boxes.getBoxByBuilderId(pool, builderId);
-      const state = box ? box.state : 'none';
-      // canTransition('deprovision', …) is the single source of truth for which
-      // states hold a droplet/snapshot worth reclaiming (active/parking/parked/
-      // waking/error). none/destroyed/provisioning → nothing to close.
-      if (!box || !boxes.canTransition('deprovision', state)) {
-        return res.fail('box_not_closeable', { status: 409, message: state === 'none' || state === 'destroyed'
-            ? 'That builder has no box to close.'
-            : `Box is '${state}' — nothing to deprovision right now.`, details: { state } });
-      }
-      const { created } = await boxes.enqueueIntent(
-        pool, builderId, 'deprovision', `api:archon:${req.builder.id}`
-      );
-      if (created) {
-        await boxes.recordEvent(pool, {
-          boxId: box.id, builderId, event: 'intent_enqueue',
-          detail: `deprovision (archon close by ${req.builder.github_login || req.builder.id})`,
-          actor: `archon:${req.builder.id}`,
-        }).catch(() => {});
-      }
-      res.json({
-        ok: true, queued: created, action: 'deprovision', state,
-        message: created
-          ? 'The box will be closed shortly.'
-          : 'A close request is already queued for that box.',
-      });
-    } catch (err) {
-      log.error('[gds] POST /boxes/:builderId/close', err);
-      res.fail('close_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // PATCH /boxes/:builderId/block — Archon bars (or un-bars) a builder from
-  // OPENING dev boxes (idea 257 / task 1163; migration 104). Body:
-  //   { blocked: bool (required),
-  //     reason?: string,         // recorded on block; shown back to the builder
-  //     close_current?: bool }   // on block, ALSO deprovision a running box
-  // Block alone is "no new opens" (decideEnsureAction → BOX_PROVISION_BLOCKED);
-  // it does NOT touch a box that is already active. close_current adds the
-  // explicit teardown the owner asked be optional ("options for both"). rank:
-  // archon. Archon-first ordering (see above).
-  router.patch('/boxes/:builderId/block', auth.requireBuilder, auth.requirePermission('box.fleet.manage'), async (req, res) => {
-    const builderId = Number(req.params.builderId);
-    if (!Number.isInteger(builderId) || builderId < 1) {
-      return res.fail('bad_builder_id', 400);
-    }
-    if (validateOrRespond(req, res, {
-      blocked: { required: true, type: 'boolean' },
-      reason: { type: 'string', maxLength: 500 },
-      close_current: { type: 'boolean' },
-    })) return;
-    const { blocked, reason, close_current: closeCurrent } = req.body || {};
-    try {
-      const updated = await db.setBuilderBoxBlocked(builderId, {
-        blocked,
-        reason: blocked ? (reason || null) : null,
-        actorBuilderId: req.builder.id,
-      });
-      if (!updated) return res.fail('builder_not_found', 404);
-
-      let closeQueued = false;
-      if (blocked) {
-        // Ensure a builder_boxes row exists so a blocked builder appears on the
-        // Harbor roster (state='none') even if they never opened a box — an
-        // Archon can bar a newcomer pre-emptively.
-        const box = await boxes.ensureBoxRow(pool, builderId);
-        await boxes.recordEvent(pool, {
-          boxId: box.id, builderId, event: 'box_blocked',
-          detail: `blocked by ${req.builder.github_login || req.builder.id}${reason ? ` — ${reason}` : ''}`,
-          actor: `archon:${req.builder.id}`,
-        }).catch(() => {});
-        if (closeCurrent && boxes.canTransition('deprovision', box.state)) {
-          const { created } = await boxes.enqueueIntent(
-            pool, builderId, 'deprovision', `api:archon:${req.builder.id}`
-          );
-          closeQueued = created;
-          if (created) {
-            await boxes.recordEvent(pool, {
-              boxId: box.id, builderId, event: 'intent_enqueue',
-              detail: 'deprovision (block + close current)',
-              actor: `archon:${req.builder.id}`,
-            }).catch(() => {});
-          }
-        }
-      } else {
-        const box = await boxes.getBoxByBuilderId(pool, builderId);
-        if (box) {
-          await boxes.recordEvent(pool, {
-            boxId: box.id, builderId, event: 'box_unblocked',
-            detail: `unblocked by ${req.builder.github_login || req.builder.id}`,
-            actor: `archon:${req.builder.id}`,
-          }).catch(() => {});
-        }
-      }
-
-      res.json({
-        ok: true,
-        blocked: {
-          is: !!updated.box_blocked,
-          reason: updated.box_blocked_reason || null,
-          at: updated.box_blocked_at || null,
-        },
-        close_queued: closeQueued,
-      });
-    } catch (err) {
-      log.error('[gds] PATCH /boxes/:builderId/block', err);
-      res.fail('block_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // GET /box/me — the caller's own box. rank: any authenticated builder (own
-  // resource read). Returns { box: { state:'none' } } when they have no box yet.
-  router.get('/box/me', auth.requireBuilder, async (req, res) => {
-    try {
-      const row = await boxes.getBoxByBuilderId(pool, req.builder.id);
-      // Surface any open intent so a returning builder sees "queued" without
-      // having to re-POST /box/ensure.
-      const open = await boxes.getOpenIntent(pool, req.builder.id);
-      // #602: the caller's own running container-cost total (spin-up + compute +
-      // storage). Own-scoped — keyed on req.builder.id, never another builder.
-      const cost = await boxes.boxCostSummaryForBuilder(pool, req.builder.id);
-      res.json({
-        box: publicBox(row),
-        open_intent: open
-          ? { action: open.action, state: open.state }
-          : null,
-        cost,
-      });
-    } catch (err) {
-      log.error('[gds] GET /box/me', err);
-      res.fail('box_read_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // GET /box/source-access — the box fetches its rank-scoped clone spec + the
-  // credential to pull it (ADR 0031 §6, #600). rank: any authenticated builder
-  // (own resource) — the ALLOW/DENY and the SCOPE are decided INSIDE from the
-  // caller's LIVE rank+status, NOT by a static requireRank: a Xenos must still get
-  // their 'starter' credential, a Metic+ gets 'full', and a below-floor / inactive
-  // builder is denied (403). This is ADR 0016 server-enforcement extended from
-  // "writes are gated" to "source is gated": the box presents the BUILDER's
-  // session, the GDS reads the live DB rank (unforgeable from the box), so a
-  // demoted/deactivated builder is cut off on their VERY NEXT fetch — the instant,
-  // credential-layer half of the offboarding clawback (the droplet teardown is the
-  // slower control-plane half via `box.js reconcile`). The credential is returned
-  // ONLY here, from the prod env (never the repo — ADR 0022), and is NEVER logged
-  // or exposed by publicBox()/the roster.
-  // #919: allowBoxScope — one of the 4 endpoints the on-box crons call, so a
-  // box-scoped session (source='box') is permitted here. box-source-fetch.sh (cron */10).
-  router.get('/box/source-access', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
-    try {
-      // ONE consistent read of rank + status from the same row (ADR 0016: fresh
-      // per request). Deliberately NOT (req.builder.rank from the session) +
-      // (status from a second query): on a credential-issuing path those two reads
-      // could straddle a concurrent deactivation (TOCTOU). getBuilderById is the
-      // single snapshot the decision is made on; null → fail closed.
-      const builder = await gdsDb.getBuilderById(req.builder.id);
-      const rank = builder ? builder.rank : null;
-      const status = builder ? builder.status : 'inactive';
-
-      // R94 (ADR 0148 §4 / goal 1000051): scope the box to the CODE THE BUILDER'S
-      // CLAIMED TASK NEEDS. Resolve the lifecycle port (OPTIONAL — resolveOptional
-      // returns null on a vanilla instance without it) and read the set-union of the
-      // builder's active claims' module scope. scopeKeys drives the sparse BREADTH:
-      //   - array present → TASK scope (BASE ∪ the claims' module dirs; empty → BASE-only)
-      //   - undefined     → decideSourceAccess falls back to the RANK scope (the
-      //                     pre-ADR-0148 behavior, so a port-less instance is unchanged).
-      // NEVER fail the source fetch on a scope-read hiccup — degrade to rank scope.
-      // While task-scoping is paused (taskScopingPaused above), skip the claim
-      // resolution entirely: undefined scopeKeys IS the rank-fallback signal.
-      const lifecycle = api.resolveOptional('lifecycle');
-      let scopeKeys;
-      let hasActiveClaims;
-      if (!taskScopingPaused() && lifecycle && typeof lifecycle.moduleScopeForActiveClaims === 'function') {
-        try {
-          scopeKeys = await lifecycle.moduleScopeForActiveClaims(req.builder.id);
-        } catch (scopeErr) {
-          log.error('[gds] source-access scope read (non-fatal, → rank scope)', scopeErr && scopeErr.message ? scopeErr.message : scopeErr);
-          scopeKeys = undefined;
-        }
-      }
-      // task 1002729 — only needed to disambiguate an EMPTY scope: no claim (BASE)
-      // vs claims whose goals declare no wall (rank scope). Skipped otherwise so
-      // the common path keeps its single query.
-      if (Array.isArray(scopeKeys) && scopeKeys.length === 0
-          && lifecycle && typeof lifecycle.activeClaimCountForBuilder === 'function') {
-        try {
-          hasActiveClaims = (await lifecycle.activeClaimCountForBuilder(req.builder.id)) > 0;
-        } catch (claimErr) {
-          log.error('[gds] source-access claim-count read (non-fatal, → BASE)', claimErr && claimErr.message ? claimErr.message : claimErr);
-          hasActiveClaims = undefined;
-        }
-      }
-      // Read the box BEFORE deciding: its widen_paths are an INPUT to the sparse
-      // set now (task 1003087). A builder-requested directory is unioned in here,
-      // which is what makes it survive the */10 cron — the cron re-asks THIS
-      // endpoint every tick, so the union comes back with it instead of being
-      // deleted by the next `git sparse-checkout set`.
-      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
-      const decision = boxAccess.decideSourceAccess({
-        rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap,
-        widenPaths: box ? box.widen_paths : null,
-      });
-      const auditDeny = (reason, extra) =>
-        box && boxAccess.recordSourceEvent(pool, {
-          box, builderId: req.builder.id, event: 'source_deny',
-          detail: `${reason}${extra ? ` ${extra}` : ''}`, actor: 'api',
-        }).catch(() => {});
-
-      if (!decision.allowed) {
-        await auditDeny(decision.reason, decision.required ? `(required ${decision.required}, had ${decision.actual ?? 'none'})` : '');
-        return res.fail('SOURCE_ACCESS_REVOKED', 403, { reason: decision.reason, required: decision.required ?? null, actual: decision.actual ?? null });
-      }
-
-      // The credential is issued ONLY to a LIVE box (defense-in-depth: "the box
-      // holds the credential" — a stolen token used off-box, or a builder with no /
-      // parked box, gets nothing). The box calls this while active; on first
-      // provision / wake it is active by the time its cron fetches.
-      if (!box || !boxAccess.boxCanHoldSource(box.state)) {
-        await auditDeny('NO_ACTIVE_BOX', `(box_state=${box ? box.state : 'none'})`);
-        return res.fail('SOURCE_ACCESS_REVOKED', 403, { reason: 'NO_ACTIVE_BOX', box_state: box ? box.state : 'none' });
-      }
-
-      // Mint the scope-appropriate credential (operator-supplied; may be unconfigured).
-      // ADR 0148 C4 leaves the TOKEN MODEL untouched: the credential (which repo +
-      // which token) stays RANK-based, exactly as before task-scoping. decision.scope
-      // may now be 'task'/'base' (the sparse BREADTH the box ASKS for), but the
-      // credential must still be the rank one — issue() only special-cases 'full', so
-      // passing 'task'/'base' would hand even a Metic+ the STARTER repo/token, which on
-      // a separate-starter-repo instance can't reach the task's module. Task-scope is
-      // the CLIENT-SIDE sparse ask; a hard per-claim credential ceiling is the deferred
-      // hardening (ADR 0148 Consequences).
-      const credScope = boxes.boxScopeForRank(rank); // 'starter' | 'full' — unchanged posture
-      const cred = boxCredential.defaultProvider.issue(credScope, { nowMs: Date.now() });
-
-      // Audit the grant — scope + configured flag only, NEVER the token. Only a
-      // REAL (configured) grant is logged: an unconfigured fetch issued no
-      // credential, so it is not an access event. Retention: box_events is
-      // append-only audit; a source_grant lands ~6×/hour per active box (the
-      // refresh cadence), so the box-lifecycle sweeps' retention should prune
-      // source_grant rows beyond a short window — the security-critical
-      // source_deny / source_revoke / source_reconcile events are far rarer and
-      // are what an audit actually reads.
-      if (box && cred.configured) {
-        await boxAccess.recordSourceEvent(pool, {
-          box, builderId: req.builder.id, event: 'source_grant',
-          detail: `scope=${decision.scope} cred=${credScope} mode=${decision.spec.mode}`,
-          actor: 'api',
-        }).catch(() => {});
-      }
-
-      return res.json({
-        scope: decision.scope,
-        mode: decision.spec.mode,
-        sparse_paths: decision.spec.sparsePaths,
-        repo_url: cred.repoUrl,
-        credential: cred.token,            // null when unconfigured
-        configured: cred.configured,
-        separate_starter_repo: cred.separateStarterRepo,
-        expires_at: cred.expiresAt,
-        ttl_seconds: cred.ttlSeconds ?? null,
-        guidance: cred.guidance,
-      });
-    } catch (err) {
-      // Log the detail server-side; do NOT leak it to the caller — this is a
-      // credential-issuing endpoint, and err.message can carry DB/query internals.
-      log.error('[gds] GET /box/source-access', err);
-      res.fail('source_access_failed', 500);
-    }
-  });
-
-  // GET /box/scope — the credential-FREE companion to /box/source-access
-  // (BV1.R100 / goal 1000051). Answers "what code does my box hold RIGHT NOW?" —
-  // the resolved sparse set + the module keys of the builder's active claims —
-  // WITHOUT issuing the pull credential. The laptop app reads it to confirm
-  // "your box now has <module> for task N" after a pick+claim; R104's proof reads
-  // it to VERIFY the scope is minimal (excludes other modules). Same live rank+
-  // status + lifecycle-port scope logic as source-access, so the answer can't
-  // drift from the actual checkout — it just omits the secret.
-  //
-  // Deliberately NOT gated on a live box (boxCanHoldSource): the SCOPE is metadata,
-  // so a builder can ask "what WOULD my box hold for my current claims" the instant
-  // they claim, before the box has even synced. The ALLOW/DENY still comes from the
-  // live rank+status (a demoted/inactive builder gets the same 403 as source-access).
-  // allowBoxScope so it works both from the laptop app (full session) and on the box
-  // (box-scoped session) — safe here precisely because no credential is returned.
-  router.get('/box/scope', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
-    try {
-      // ONE consistent rank+status snapshot (the /box/source-access TOCTOU note).
-      const builder = await gdsDb.getBuilderById(req.builder.id);
-      const rank = builder ? builder.rank : null;
-      const status = builder ? builder.status : 'inactive';
-
-      // Resolve the claim-driven module scope exactly as source-access does
-      // (optional lifecycle port; degrade to rank scope on any hiccup; skipped
-      // entirely while task-scoping is paused, so this read-only companion can
-      // never report a slice the real fetch would no longer grant).
-      const lifecycle = api.resolveOptional('lifecycle');
-      let scopeKeys;
-      let hasActiveClaims;
-      if (!taskScopingPaused() && lifecycle && typeof lifecycle.moduleScopeForActiveClaims === 'function') {
-        try {
-          scopeKeys = await lifecycle.moduleScopeForActiveClaims(req.builder.id);
-        } catch (scopeErr) {
-          log.error('[gds] /box/scope scope read (non-fatal, → rank scope)', scopeErr && scopeErr.message ? scopeErr.message : scopeErr);
-          scopeKeys = undefined;
-        }
-      }
-      // task 1002729 — same disambiguation as source-access, so this read-only
-      // companion can never report a scope the real fetch wouldn't grant.
-      if (Array.isArray(scopeKeys) && scopeKeys.length === 0
-          && lifecycle && typeof lifecycle.activeClaimCountForBuilder === 'function') {
-        try {
-          hasActiveClaims = (await lifecycle.activeClaimCountForBuilder(req.builder.id)) > 0;
-        } catch (claimErr) {
-          log.error('[gds] /box/scope claim-count read (non-fatal, → BASE)', claimErr && claimErr.message ? claimErr.message : claimErr);
-          hasActiveClaims = undefined;
-        }
-      }
-      // Same widen input as the real fetch — this readout exists precisely so it
-      // cannot drift from what the box will actually hold.
-      const scopeBox = await boxes.getBoxByBuilderId(pool, req.builder.id);
-      const decision = boxAccess.decideSourceAccess({
-        rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap,
-        widenPaths: scopeBox ? scopeBox.widen_paths : null,
-      });
-      if (!decision.allowed) {
-        return res.fail('SOURCE_ACCESS_REVOKED', 403, {
-          reason: decision.reason,
-          required: decision.required ?? null,
-          actual: decision.actual ?? null,
-        });
-      }
-      const meta = boxAccess.scopeMetadata({ decision, scopeKeys });
-      // task_scope true only when a claim actually drove the breadth (scopeKeys is
-      // an array). false → the rank fallback (no active claim / no lifecycle port /
-      // task-scoping paused — the paused flag says which, so the app can explain).
-      return res.json({ ...meta, task_scope: Array.isArray(scopeKeys), task_scoping_paused: taskScopingPaused() });
-    } catch (err) {
-      log.error('[gds] GET /box/scope', err);
-      res.fail('box_scope_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // POST /box/heartbeat — the box reports it is alive, resetting the idle clock.
-  // rank: any authenticated builder (own resource write). Optional body:
-  // { claude_active: bool, attached: bool }.
-  //
-  // `claude_active` records whether a `claude` process is running; the idle sweep
-  // honours it as a veto, but since task 1003507 only for BOX_UNATTENDED_MAX_HOURS
-  // (a running process is not a person, and an unbounded veto pinned boxes active
-  // forever). `attached` is the human signal — a login session, an inbound SSH
-  // connection, an open browser terminal, or an attached tmux client — and stamps
-  // last_attached_at, the clock that cap is measured against. A heartbeat that
-  // omits `attached` (any box still running the pre-1003507 script) leaves the
-  // column NULL, which the sweep reads as "no data" and not as "unattended".
-  // Heartbeats without a body behave as before (last_activity_at bumped only).
-  // #919: allowBoxScope — box-heartbeat.sh (cron */5) runs with the box-scoped session.
-  router.post('/box/heartbeat', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
-    // strict:false — heartbeat is a machine ping from SHIPPED box clients that
-    // can't update in lockstep with the server (the ADR-0117 un-updatable-consumer
-    // concern). Validate the known field's type, but tolerate a future/extra field
-    // rather than reject a resilience-critical ping (the idle sweep keys off it).
-    if (validateOrRespond(req, res, { claude_active: { type: 'boolean' }, attached: { type: 'boolean' } }, { strict: false })) return;
-    try {
-      const body = req.body || {};
-      const claudeActive = typeof body.claude_active === 'boolean' ? body.claude_active : undefined;
-      const attached = typeof body.attached === 'boolean' ? body.attached : undefined;
-      const state = await boxes.bumpActivity(pool, req.builder.id, { claudeActive, attached });
-      res.json({ ok: true, state: state || 'none' });
-    } catch (err) {
-      log.error('[gds] POST /box/heartbeat', err);
-      res.fail('heartbeat_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // POST /box/close — the builder manually requests their box be deprovisioned.
-  // rank: any authenticated builder (own resource). Enqueues a 'deprovision'
-  // intent; the control-plane runner executes it so the web tier never holds
-  // DO_API_TOKEN (trust boundary holds, same as /box/ensure). Only valid for an
-  // active box — a box that isn't running has nothing to close.
-  router.post('/box/close', auth.requireBuilder, async (req, res) => {
-    try {
-      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
-      const state = box ? box.state : 'none';
-      if (state !== 'active') {
-        return res.fail('box_not_active', { status: 409, message: state === 'none' || state === 'destroyed'
-            ? 'No active box to close.'
-            : `Box is currently '${state}' — wait for it to finish or ask a Metic+ operator.`, details: { state } });
-      }
-      const { intent, created } = await boxes.enqueueIntent(
-        pool, req.builder.id, 'deprovision', 'api:self'
-      );
-      if (created) {
-        await boxes.recordEvent(pool, {
-          boxId: box.id, builderId: req.builder.id, event: 'intent_enqueue',
-          detail: 'deprovision (manual close from hall)', actor: 'api',
-        }).catch(() => {});
-      }
-      res.json({
-        ok: true, queued: created, action: 'deprovision',
-        message: created
-          ? 'Your box will be closed shortly.'
-          : 'A close request is already queued for your box.',
-      });
-    } catch (err) {
-      log.error('[gds] POST /box/close', err);
-      res.fail('close_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // ─── #685: one-command onboarding — SSH-key registry + box pull ──────────
-  // The block below removes the operator SSH round-trip: the builder registers
-  // their OWN public key, and the box pulls authorized_keys from here (gated on
-  // live rank, like source). Every route is requireBuilder (own resource); none
-  // is archon, so the any-builder routes can follow heartbeat without tripping
-  // the route-rank auditor's archon-first ordering. The PUBLIC connect routes
-  // come dead last (see their `rank: public` annotations).
-
-  // POST /box/ssh-key — register the caller's own public SSH key. rank: any
-  // authenticated builder (own resource write). The key is validated +
-  // normalized (box-onboard.validateSshPublicKey) so nothing attacker-shaped can
-  // reach the box's authorized_keys; the audit_log middleware records the write.
-  router.post('/box/ssh-key', auth.requireBuilder, async (req, res) => {
-    if (validateOrRespond(req, res, {
-      public_key: { required: true, type: 'string', maxLength: 20000 },
-      label: { type: 'string', maxLength: LIMITS.TAG },
-    })) return;
-    const v = boxOnboard.validateSshPublicKey((req.body || {}).public_key);
-    if (!v.ok) {
-      return res.fail('bad_ssh_key', 400, { reason: v.error });
-    }
-    try {
-      // Per-builder cap (bloat-prevention; see MAX_SSH_KEYS_PER_BUILDER). A
-      // re-register of an EXISTING fingerprint is always allowed (it's an
-      // upsert, not growth) — only a NEW key past the cap is refused, so a
-      // builder at the cap can still rotate/relabel their existing keys.
-      const existing = await boxOnboard.listSshKeys(pool, req.builder.id);
-      const isNew = !existing.some((k) => k.fingerprint === v.fingerprint);
-      if (isNew && existing.length >= boxOnboard.MAX_SSH_KEYS_PER_BUILDER) {
-        return res.fail('too_many_keys', 400, { limit: boxOnboard.MAX_SSH_KEYS_PER_BUILDER });
-      }
-      const label = boxOnboard.sanitizeLabel((req.body || {}).label) || v.label;
-      const row = await boxOnboard.registerSshKey(pool, req.builder.id, {
-        publicKey: v.normalized, keyType: v.keyType, fingerprint: v.fingerprint, label,
-      });
-      res.status(201).json({
-        ok: true,
-        key: { id: row.id, key_type: row.key_type, fingerprint: row.fingerprint, label: row.label },
-      });
-    } catch (err) {
-      log.error('[gds] POST /box/ssh-key', err);
-      res.fail('register_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // GET /box/ssh-key — list the caller's registered keys. rank: any builder (own).
-  router.get('/box/ssh-key', auth.requireBuilder, async (req, res) => {
-    try {
-      const rows = await boxOnboard.listSshKeys(pool, req.builder.id);
-      res.json({
-        keys: rows.map((r) => ({
-          id: r.id, key_type: r.key_type, fingerprint: r.fingerprint,
-          label: r.label, created_at: r.created_at, last_used_at: r.last_used_at,
-        })),
-      });
-    } catch (err) {
-      log.error('[gds] GET /box/ssh-key', err);
-      res.fail('list_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // DELETE /box/ssh-key/:id — remove one of the caller's keys. rank: any builder
-  // (own resource; the delete is builder_id-scoped in SQL so an id from another
-  // builder cannot be removed). 404 when the id isn't the caller's.
-  router.delete('/box/ssh-key/:id', auth.requireBuilder, async (req, res) => {
-    const id = Number.parseInt(req.params.id, 10);
-    if (!Number.isInteger(id) || id <= 0) return res.fail('bad_id', 400);
-    try {
-      const removed = await boxOnboard.deleteSshKey(pool, req.builder.id, id);
-      if (!removed) return res.fail('not_found', 404);
-      res.json({ ok: true, deleted: removed });
-    } catch (err) {
-      log.error('[gds] DELETE /box/ssh-key/:id', err);
-      res.fail('delete_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // GET /box/widen — the caller's own recorded widen set (task 1003087).
-  // rank: any authenticated builder, own resource. Reports what is STORED plus
-  // what is currently ADMITTED, because those differ whenever a request sits
-  // outside the builder's rank scope — showing only the stored list would let a
-  // Xenos believe a widen took effect that the fetch quietly drops.
-  router.get('/box/widen', auth.requireBuilder, async (req, res) => {
-    try {
-      const builder = await gdsDb.getBuilderById(req.builder.id);
-      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
-      if (!box) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
-      const stored = Array.isArray(box.widen_paths) ? box.widen_paths : [];
-      const admitted = boxAccess.admissibleWidenPaths(stored, builder ? builder.rank : null);
-      res.json({
-        widen_paths: stored,
-        admitted,
-        ignored: stored.filter((p) => !admitted.includes(boxAccess.normalizeWidenPath(p))),
-        max: boxAccess.MAX_WIDEN_PATHS,
-      });
-    } catch (err) {
-      log.error('[gds] GET /box/widen', err);
-      res.fail('widen_read_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // POST /box/widen — record extra sparse-checkout directories that must SURVIVE
-  // the */10 source-fetch (task 1003087, idea 1000793). rank: any authenticated
-  // builder, OWN box (builder_id-scoped in SQL, so no id from the body can point
-  // this at someone else's box).
-  //
-  // Deliberately NOT allowBoxScope. The on-box crons read source-access with a
-  // box-scoped session (ADR 0053); this is a WRITE that changes what the box
-  // pulls forever after, so it takes the builder's own session — the same posture
-  // that keeps a stolen box token from re-scoping the checkout it was stolen from.
-  //
-  // add/remove are applied to the stored set and the result is re-normalized, so
-  // the endpoint is idempotent: widening twice is not an error, and neither is
-  // removing something that was never there.
-  //
-  // A path outside the caller's rank scope is ACCEPTED into storage but reported
-  // in `ignored` rather than refused. That is the honest shape: rank can change,
-  // and a builder promoted to Metic should find the widen they asked for as a
-  // Xenos simply start working, instead of having been silently discarded months
-  // earlier. What it can never do is take effect early — admissibleWidenPaths is
-  // re-evaluated against the LIVE rank on every single fetch.
-  router.post('/box/widen', auth.requireBuilder, async (req, res) => {
-    if (validateOrRespond(req, res, {
-      add: { type: 'array' },
-      remove: { type: 'array' },
-      clear: { type: 'boolean' },
-    })) return;
-    try {
-      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
-      if (!box) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
-      const builder = await gdsDb.getBuilderById(req.builder.id);
-
-      const current = Array.isArray(box.widen_paths) ? box.widen_paths : [];
-      const next = new Set(req.body && req.body.clear === true ? [] : current);
-
-      const rejected = [];
-      for (const raw of Array.isArray(req.body && req.body.add) ? req.body.add : []) {
-        const p = boxAccess.normalizeWidenPath(raw);
-        if (!p) { rejected.push(String(raw).slice(0, 120)); continue; }
-        next.add(p);
-      }
-      for (const raw of Array.isArray(req.body && req.body.remove) ? req.body.remove : []) {
-        const p = boxAccess.normalizeWidenPath(raw);
-        if (p) next.delete(p);
-      }
-      if (rejected.length) {
-        return res.fail('bad_widen_path', 400, {
-          rejected,
-          message: 'a widen path must be a repo-relative directory: no absolute paths, no "..", no drive letters',
-        });
-      }
-
-      const stored = [...next].sort().slice(0, boxAccess.MAX_WIDEN_PATHS);
-      const saved = await boxes.setBoxWidenPaths(pool, req.builder.id, stored);
-      if (saved === null) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
-      const admitted = boxAccess.admissibleWidenPaths(saved, builder ? builder.rank : null);
-      res.json({
-        ok: true,
-        widen_paths: saved,
-        admitted,
-        ignored: saved.filter((p) => !admitted.includes(p)),
-        max: boxAccess.MAX_WIDEN_PATHS,
-      });
-    } catch (err) {
-      log.error('[gds] POST /box/widen', err);
-      res.fail('widen_failed', { status: 500, message: 'internal error' });
-    }
-  });
-
-  // GET /box/authorized-keys — the box pulls its builder's authorized_keys.
-  // rank: any authenticated builder (own resource) — but the ALLOW/DENY is decided
-  // INSIDE from the caller's LIVE rank+status (boxAccess.decideSourceAccess), NOT a
-  // static requireRank, mirroring /box/source-access: a demoted/deactivated builder
-  // is 403'd and the box-side fetch empties the managed authorized_keys block on the
-  // very next cron — instant SSH-login revocation (ADR 0016 extended to login). The
-  // body is text/plain: the managed key LINES (no markers — the box wraps them). An
-  // allowed builder with no registered keys gets an empty 200 (a valid empty block).
-  // #919: allowBoxScope — box-authorized-keys-fetch.sh (cron */10) runs box-scoped.
-  router.get('/box/authorized-keys', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
-    try {
-      // One consistent rank+status snapshot (the /box/source-access TOCTOU note).
-      const builder = await gdsDb.getBuilderById(req.builder.id);
-      const rank = builder ? builder.rank : null;
-      const status = builder ? builder.status : 'inactive';
-      const decision = boxAccess.decideSourceAccess({ rank, status });
-      if (!decision.allowed) {
-        const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
-        if (box) {
-          await boxAccess.recordSourceEvent(pool, {
-            box, builderId: req.builder.id, event: 'authkeys_deny',
-            detail: `${decision.reason}${decision.required ? ` (required ${decision.required}, had ${decision.actual ?? 'none'})` : ''}`,
-            actor: 'api',
-          }).catch(() => {});
-        }
-        return res.fail('BOX_ACCESS_REVOKED', 403, { reason: decision.reason, required: decision.required ?? null, actual: decision.actual ?? null });
-      }
-      const keys = await boxOnboard.listSshKeys(pool, req.builder.id);
-      await boxOnboard.touchSshKeysUsed(pool, req.builder.id).catch(() => {});
-      res.type('text/plain').send(boxOnboard.buildAuthorizedKeysFile(keys));
-    } catch (err) {
-      log.error('[gds] GET /box/authorized-keys', err);
-      res.fail('authorized_keys_failed', 500);
-    }
-  });
-
-  // GET /box/managed-settings — the caller's Claude Desktop managed-settings.json.
-  // rank: any authenticated builder (own resource; non-secret — just their box
-  // hostname + the SSH identity path). Issued regardless of box state: the builder
-  // needs it on disk BEFORE the operator provisions, then connects once the box is up.
-  router.get('/box/managed-settings', auth.requireBuilder, async (req, res) => {
-    try {
-      const login = req.builder.github_login;
-      const settings = boxOnboard.buildManagedSettings({ login, hostname: hostnameForLogin(login), world: devBoxWorld(), sshZone: boxDnsZone() });
-      res.json(settings);
-    } catch (err) {
-      // BAD_LOGIN/BAD_HOSTNAME are 400-class (a malformed login should never reach
-      // here for a real builder, but fail clean rather than 500).
-      if (err && (err.code === 'BAD_LOGIN' || err.code === 'BAD_HOSTNAME')) {
-        return res.fail('bad_identity', { status: 400, message: 'internal error' });
-      }
-      log.error('[gds] GET /box/managed-settings', err);
-      res.fail('managed_settings_failed', 500);
-    }
-  });
-
-  // ─── #701/#760: box onboarding middleware — auto-provision + wake-on-connect +
-  // web/Chromebook terminal access (ADR 0038) ──────────────────────────────
-  // These three are the TRUST-BOUNDARY-SAFE on-ramp: the web process records a
-  // REQUEST (an intent) or reads published terminal access — it NEVER touches the
-  // DigitalOcean API (the header's invariant holds). The control-plane runner
-  // (box.js run-intents, the box-intent-runner timer) drains the queue and does
-  // the real provision/wake. All three are requireBuilder (own resource); none is
-  // archon, so they sit between heartbeat/ssh-key and the public connect routes
-  // without tripping the route-rank auditor's archon-first ordering.
-
-  // POST /box/ensure — "make my box ready". rank: any authenticated builder (own
-  // resource) — the ALLOW/DENY + the chosen ACTION are decided INSIDE from the
-  // caller's LIVE rank+status (boxes.decideEnsureAction), NOT a static requireRank,
-  // mirroring /box/source-access. This single call covers BOTH halves of #701's
-  // gap: a builder with no box gets a provision queued (auto-provision), a builder
-  // whose box is parked gets a wake queued (wake-on-connect). It enqueues at most
-  // one open intent per builder; the actual DO work happens on the control plane.
-  router.post('/box/ensure', auth.requireBuilder, async (req, res) => {
-    try {
-      // One consistent rank+status snapshot from the live DB (the source-access
-      // TOCTOU note): never trust the session copy on a provisioning path.
-      const builder = await gdsDb.getBuilderById(req.builder.id);
-      const rank = builder ? builder.rank : null;
-      const status = builder ? builder.status : 'inactive';
-      const box = await boxes.ensureBoxRow(pool, req.builder.id);
-      const decision = boxes.decideEnsureAction({
-        boxState: box.state, rank, status,
-        blocked: !!(builder && builder.box_blocked),
-        floor: provisionFloor(),
-      });
-
-      if (decision.action === 'denied') {
-        const payload = {
-          error: 'BOX_PROVISION_DENIED', reason: decision.reason,
-          required: decision.required ?? null, actual: decision.actual ?? null,
-        };
-        // idea 257 / task 1163: when an operator block is the cause, tell the
-        // builder WHY (the recorded reason) rather than a bare denial — this is
-        // the `message` the box-panel surfaces to the builder verbatim. The block
-        // is written by a Metic+ operator (box.fleet.manage, ADR 0157), so don't
-        // attribute it to an Archon specifically.
-        if (decision.reason === 'BOX_PROVISION_BLOCKED') {
-          payload.message = builder && builder.box_blocked_reason
-            ? `An operator has paused thy dev-box access: ${builder.box_blocked_reason}`
-            : 'An operator has paused thy dev-box access. Ask in Discord #support.';
-        }
-        return res.status(403).json(payload);
-      }
-      if (decision.action === 'ready') {
-        // Already up — treat the connect as a heartbeat so it doesn't get parked
-        // out from under the builder who just asked for it.
-        await boxes.bumpActivity(pool, req.builder.id);
-        return res.json({ state: 'active', action: 'ready', queued: false });
-      }
-      if (decision.action === 'in_progress') {
-        const open = await boxes.getOpenIntent(pool, req.builder.id);
-        return res.json({ state: box.state, action: 'in_progress', queued: false, intent: open ? open.action : null });
-      }
-
-      // provision | wake → enqueue an intent (idempotent: an already-open intent
-      // is returned rather than duplicated).
-      const { intent, created } = await boxes.enqueueIntent(
-        pool, req.builder.id, decision.action, 'api:self'
-      );
-      if (created) {
-        await boxes.recordEvent(pool, {
-          boxId: box.id, builderId: req.builder.id, event: 'intent_enqueue',
-          detail: `${decision.action} (from state=${box.state})`,
-          actor: 'api',
-        }).catch(() => {});
-      }
-      return res.status(created ? 202 : 200).json({
-        state: box.state, action: intent.action, queued: created,
-        message: created
-          ? `Your box will be ${intent.action === 'wake' ? 'woken' : 'created'} shortly — check back in a minute.`
-          : `A ${intent.action} is already queued for your box.`,
-      });
-    } catch (err) {
-      log.error('[gds] POST /box/ensure', err);
-      res.fail('ensure_failed', 500);
-    }
-  });
-
-  // GET /box/terminal — the caller reads their box's web-terminal URL + credential
-  // (the Chromebook on-ramp, ADR 0038: ttyd behind a Cloudflare Tunnel). rank: any
-  // authenticated builder (own resource). Read-only by design: it does NOT wake a
-  // parked box (that mutation belongs to POST /box/ensure). The Chromebook flow is:
-  // POST /box/ensure → poll this until state='active' and a url appears → open the
-  // url, enter the basic-auth credential, run `claude` in the terminal. The url AND
-  // credential are returned ONLY to the box's own builder, and are null until the
-  // box's terminal reporter (box-report-terminal.sh) has published them.
-  router.get('/box/terminal', auth.requireBuilder, async (req, res) => {
-    try {
-      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
-      const state = box ? box.state : 'none';
-      if (state !== 'active') {
-        return res.json({
-          state, url: null, credential: null,
-          hint: state === 'parked' || state === 'none' || state === 'destroyed'
-            ? 'No active box — POST /box/ensure first, then poll this endpoint.'
-            : 'Box is starting up — poll again shortly.',
-        });
-      }
-      // If the DB has a URL, probe it before handing out credentials — the URL
-      // is recorded at provision time (#774), BEFORE cloudflared connects, so the
-      // probe (via isTunnelReadyStatus, #889) is what distinguishes a live tunnel
-      // from a box that is still booting / a CF 1033 (530) error page.
-      // SECURITY (#871): never fetch (SSRF) or serve a stored URL that isn't a
-      // valid tunnel host — e.g. a row written before this allow-list landed.
-      if (box.terminal_url && !isSafeTerminalUrl(box.terminal_url, req.builder.github_login)) {
-        return res.json({
-          state: 'active', url: null, credential: null,
-          hint: 'Terminal URL pending a valid tunnel host — reconnect your box to republish it.',
-        });
-      }
-      if (box.terminal_url) {
-        let tunnelReady = false;
-        try {
-          // L3 (red-team 2026-06-12): probe with redirect:'manual' so a 30x can't
-          // bounce this fetch to an arbitrary host (SSRF, defense-in-depth atop
-          // the isSafeTerminalUrl check on the stored URL above). On a redirect,
-          // re-run the SAME host allowlist on the Location: a redirect to a valid
-          // tunnel host is still "ready" (isTunnelReadyStatus already treats 3xx
-          // as ready); a redirect anywhere else is treated as not-ready.
-          const probe = await fetch(box.terminal_url, { redirect: 'manual', signal: AbortSignal.timeout(4000) });
-          if (probe.status >= 300 && probe.status < 400) {
-            const location = probe.headers?.get?.('location');
-            let resolved = null;
-            try { resolved = location ? new URL(location, box.terminal_url).toString() : null; } catch { resolved = null; }
-            tunnelReady = !!resolved && isSafeTerminalUrl(resolved, req.builder.github_login);
-          } else {
-            tunnelReady = isTunnelReadyStatus(probe.status);
-          }
-        } catch (_) {
-          tunnelReady = false;
-        }
-        if (!tunnelReady) {
-          return res.json({
-            state: 'active',
-            url: null,
-            credential: null,
-            warming_up: true,
-            hint: 'Box is up; tunnel is connecting — poll again in a few seconds.',
-          });
-        }
-      }
-      return res.json({
-        state: 'active',
-        url: box.terminal_url || null,
-        credential: box.terminal_credential || null,
-        terminal_at: box.terminal_at || null,
-        hint: box.terminal_url
-          ? null
-          : 'Box is up; waiting for the terminal service + tunnel to publish their URL (a few seconds after boot).',
-      });
-    } catch (err) {
-      log.error('[gds] GET /box/terminal', err);
-      res.fail('terminal_failed', 500);
-    }
-  });
-
-  // POST /box/terminal — the box publishes its current web-terminal URL + the
-  // per-box basic-auth credential. rank: any authenticated builder (own resource)
-  // — the BOX calls this as its builder, using the GDS token already on the box.
-  // Both are stored ONLY when the box is active (boxes.setTerminalAccess enforces
-  // this), so a stale URL/credential can never be served after a park. The URL is
-  // validated to a bounded https URL; the credential is a bounded opaque string
-  // (a secret), only ever returned to its own builder (GET /box/terminal).
-  // #919: allowBoxScope — box-report-terminal.sh (credsync) runs box-scoped. The GET
-  // above is the builder reading from the hall, so it stays full-auth (not box-scoped).
-  router.post('/box/terminal', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
-    if (validateOrRespond(req, res, {
-      url: { required: true, type: 'string', maxLength: 2048 },
-      credential: { required: false, type: 'string', maxLength: 512 },
-    })) return;
-    const url = String((req.body || {}).url || '').trim();
-    const credential = String((req.body || {}).credential || '').trim() || null;
-    // SECURITY (#871): allow-list to a real tunnel host bound to the caller's own
-    // login, not just "any https URL" — otherwise the GET probe below is an SSRF
-    // into internal/metadata endpoints.
-    if (!isSafeTerminalUrl(url, req.builder.github_login)) {
-      return res.fail('bad_terminal_url', 400, { reason: `must be an https tunnel URL (term-<login>.${devBoxApex()} or *.trycloudflare.com)` });
-    }
-    try {
-      const state = await boxes.setTerminalAccess(pool, req.builder.id, { url, credential });
-      if (state !== 'active') {
-        // The box isn't active in our records — refuse rather than store access
-        // we'd never serve (and that would be stale the moment it parked).
-        return res.fail('box_not_active', 409, { state: state || 'none' });
-      }
-      res.json({ ok: true, state });
-    } catch (err) {
-      log.error('[gds] POST /box/terminal', err);
-      res.fail('terminal_failed', 500);
-    }
-  });
-
-  // POST /box/host-keys — the box publishes its own PUBLIC SSH host keys (task 1187 /
-  // idea 235). rank: any authenticated builder (own resource) — the BOX calls this as
-  // its builder via the GDS token on the box; allowBoxScope so the box-scoped baked
-  // session (ADR 0053) can reach it, exactly like box-report-terminal.sh / the heartbeat
-  // reporter. Stored ONLY for an active box (setBoxHostKeys gates on it). Served back to
-  // the owner via GET /box/me; the connect path writes them to known_hosts authoritatively
-  // (no TOFU, no keyscan race), killing the post-re-provision "Host denied". host_keys are
-  // PUBLIC — never a secret — but the write is validated hard (anti-injection, >=1 ed25519).
-  router.post('/box/host-keys', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
-    if (validateOrRespond(req, res, {
-      host_keys: { required: true, type: 'string', maxLength: 4096 },
-    })) return;
-    const parsed = boxOnboard.validateHostKeyLines(String((req.body || {}).host_keys || ''));
-    if (!parsed.ok) {
-      return res.fail('bad_host_keys', 400, { reason: parsed.error });
-    }
-    try {
-      const state = await boxes.setBoxHostKeys(pool, req.builder.id, { hostKeys: parsed.lines.join('\n') });
-      if (state !== 'active') {
-        // Don't store host keys we'd never serve (and that would be stale once parked).
-        return res.fail('box_not_active', 409, { state: state || 'none' });
-      }
-      res.json({ ok: true, state, count: parsed.lines.length });
-    } catch (err) {
-      log.error('[gds] POST /box/host-keys', err);
-      res.fail('host_keys_failed', 500);
-    }
-  });
-
-  // POST /box/version — the box reports its /workspace HEAD commit so the server
-  // can flag a stale box (idea 332 / task 1316, ADR 0072). Body:
-  //   { sha: "<40-hex>", committed_at: "<ISO date>" }
-  // rank: any-builder — own resource (the box reports its OWN code). #919 pattern:
-  // allowBoxScope so the on-box cron (box-report-version.sh, box-scoped session)
-  // can call it, exactly like /box/host-keys + /box/heartbeat. Non-secret.
-  router.post('/box/version', auth.allowBoxScope, auth.requireBuilder, async (req, res) => {
-    if (validateOrRespond(req, res, {
-      sha: { required: true, type: 'string', maxLength: 64 },
-      committed_at: { type: 'string', maxLength: 64 },
-    })) return;
-    const body = req.body || {};
-    const sha = String(body.sha || '').trim();
-    if (!/^[0-9a-f]{7,40}$/i.test(sha)) {
-      return res.fail('bad_sha', 400);
-    }
-    // committed_at is optional but, when present, must parse — a bad date would
-    // poison the staleness comparison. Store as null if unparseable.
-    let committedAt = null;
-    if (body.committed_at) {
-      const d = new Date(body.committed_at);
-      if (Number.isNaN(d.getTime())) return res.fail('bad_committed_at', 400);
-      committedAt = d.toISOString();
-    }
-    try {
-      const state = await boxes.setBoxCodeVersion(pool, req.builder.id, { sha, committedAt });
-      if (state !== 'active') {
-        // Don't record a version for a box we aren't serving (mirrors host-keys).
-        return res.fail('box_not_active', 409, { state: state || 'none' });
-      }
-      res.json({ ok: true, state });
-    } catch (err) {
-      log.error('[gds] POST /box/version', err);
-      res.fail('version_report_failed', 500);
-    }
-  });
-
-  // GET /box/connect — the human/Claude-readable connect walkthrough.
-  // rank: public — no auth on purpose: a brand-new builder fetches this from a
-  // bare laptop (no token yet) to learn the one command that onboards them. It
-  // contains no secrets, only instructions + the public bootstrap URLs.
-  router.get('/box/connect', async (_req, res) => {
-    res.type('text/plain').send(boxOnboard.renderConnectGuide({ apiBase: PUBLIC_ORIGIN, world: devBoxWorld(), apex: devBoxApex(), sshZone: boxDnsZone() }));
-  });
-
-  // GET /box/connect.sh — the macOS/Linux bootstrap script.
-  // rank: public — non-secret installer (the rustup/nvm pattern). It does its OWN
-  // GitHub device-flow auth before it touches anything; serving it needs no auth.
-  router.get('/box/connect.sh', async (_req, res) => {
-    const script = readBootstrapScript('box-connect.sh', PUBLIC_ORIGIN);
-    if (script == null) return res.status(404).type('text/plain').send('# box-connect.sh not found on the server');
-    res.type('text/plain').send(script);
-  });
-
-  // GET /box/connect.ps1 — the Windows (PowerShell) bootstrap script.
-  // rank: public — same posture as connect.sh (non-secret installer; self-auths).
-  router.get('/box/connect.ps1', async (_req, res) => {
-    const script = readBootstrapScript('box-connect.ps1', PUBLIC_ORIGIN);
-    if (script == null) return res.status(404).type('text/plain').send('# box-connect.ps1 not found on the server');
-    res.type('text/plain').send(script);
-  });
-
-  return router;
-};
-
-// SECURITY (#871): exported PURE so the SSRF allow-list is unit-tested directly
-// (tests/box_terminal_ssrf.mjs) without a server, DB, or network.
-module.exports.isSafeTerminalUrl = isSafeTerminalUrl;
-module.exports.isTunnelReadyStatus = isTunnelReadyStatus;
-module.exports.taskScopingPaused = taskScopingPaused;