@bongos/core 1.17.0

package/scripts/gds/diagram-facts.js

@@ -0,0 +1,319 @@
+// Shared fact-extractor for the onboarding diagrams (task #357).
+//
+// Single source of truth for "what the live system actually is", used by BOTH:
+//   - the drift checker (.claude/scheduled-tasks/diagram-drift/check.js), which
+//     compares these facts against assertions.json and nudges on divergence; and
+//   - the generator (scripts/gds/gen-diagrams.js), which regenerates the
+//     mechanical diagrams (.mmd) FROM these facts on every deploy.
+//
+// Keeping both on one extractor guarantees the checker and the generator can
+// never disagree about what "live" means.
+//
+// Facts:
+//   - rank enum + default + WIRED ranks  ← migrations/ + src/bongos/ (this repo)
+//   - task-status set                    ← migrations/ (tasks_status_check)
+//   - live versions                      ← production API (/public/versions)
+//   - conceptual (03 + 04) piece states  ← authenticated /tasks/:id status per
+//                                           backing task + seeded-achievement
+//                                           count from migrations/. Degrades to
+//                                           null when no session is available.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+
+// --- comment stripping (so rank/status literals in prose don't read as wiring) ---
+// Line-based on purpose: a regex block-comment strip over concatenated files can
+// swallow real code across an unbalanced /* ... */, causing false-negatives.
+const dropComments = (s, prefixes) =>
+  s
+    .split('\n')
+    .filter((line) => {
+      const t = line.trim();
+      return !prefixes.some((p) => t.startsWith(p));
+    })
+    .join('\n');
+const stripJs = (s) => dropComments(s, ['//', '*', '/*']);
+const stripSql = (s) => dropComments(s, ['--']);
+
+// --- repo readers ---
+function readMigrations(repo) {
+  const dir = path.join(repo, 'migrations');
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.sql'))
+    .sort()
+    .map((f) => ({ name: f, text: fs.readFileSync(path.join(dir, f), 'utf8') }));
+}
+
+function readGdsSource(repo) {
+  const out = [];
+  const walk = (d) => {
+    for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+      const p = path.join(d, e.name);
+      if (e.isDirectory()) walk(p);
+      else if (e.name.endsWith('.js')) out.push(fs.readFileSync(p, 'utf8'));
+    }
+  };
+  walk(path.join(repo, 'src/bongos'));
+  return out.join('\n');
+}
+
+// --- extractors ---
+function rankEnum(migs) {
+  // Last migration that defines `rank ... CHECK (rank IN (...))` wins.
+  for (const m of [...migs].reverse()) {
+    const block = m.text.match(/rank\s+text[\s\S]*?CHECK\s*\(\s*rank\s+IN\s*\(([\s\S]*?)\)\s*\)/i);
+    if (block) return [...block[1].matchAll(/'([a-z_]+)'/gi)].map((x) => x[1]);
+  }
+  return [];
+}
+
+function defaultRank(migs) {
+  for (const m of [...migs].reverse()) {
+    // A later migration can change the column default with ALTER COLUMN SET
+    // DEFAULT (migration 029 flipped 'thetes' -> 'xenos'). Check that first so a
+    // post-CREATE change wins over the original column definition; then fall back
+    // to the CREATE/ADD COLUMN form. Reverse iteration makes the newest win.
+    const alt = m.text.match(/ALTER\s+COLUMN\s+rank\s+SET\s+DEFAULT\s+'([a-z_]+)'/i);
+    if (alt) return alt[1];
+    const d = m.text.match(/rank\s+text\s+NOT NULL\s+DEFAULT\s+'([a-z_]+)'/i);
+    if (d) return d[1];
+  }
+  return null;
+}
+
+function wiredRanks(migs, src, enum_) {
+  const wired = new Set();
+  const code = stripJs(src);
+  const inEnum = (r) => enum_.includes(r);
+  // 1. ranks named in a requireRank(...) call (gating)
+  for (const call of code.matchAll(/requireRank\(([^)]*)\)/g)) {
+    for (const lit of call[1].matchAll(/'([a-z_]+)'/g)) if (inEnum(lit[1])) wired.add(lit[1]);
+  }
+  // 2. column default
+  const def = defaultRank(migs);
+  if (def) wired.add(def);
+  // 3. rank assigned in src code, e.g. `rank = 'xenos'` (\brank avoids XENOS_RANK)
+  for (const a of code.matchAll(/\brank\s*[:=]\s*'([a-z_]+)'/gi)) if (inEnum(a[1])) wired.add(a[1]);
+  // 4. ranks SET by a migration
+  for (const m of migs) {
+    for (const s of stripSql(m.text).matchAll(/SET\s+rank\s*=\s*'([a-z_]+)'/gi)) {
+      if (inEnum(s[1])) wired.add(s[1]);
+    }
+  }
+  // 5. ranks that appear as keys in the live tier table REQUIRES_RANK_TIER
+  //    (db.js) — that map enumerates exactly the ranks the claim-gate can
+  //    compare, so membership there IS wiring. Catches ranks promoted to via a
+  //    parameterized `SET rank = $n` (e.g. thetes auto-graduation, #692) that
+  //    the literal-assignment rule above can't see.
+  const tierMap = code.match(/REQUIRES_RANK_TIER\s*=\s*\{([^}]*)\}/);
+  if (tierMap) {
+    for (const k of tierMap[1].matchAll(/([a-z_]+)\s*:/gi)) if (inEnum(k[1])) wired.add(k[1]);
+  }
+  return [...wired];
+}
+
+function taskStatuses(migs) {
+  for (const m of [...migs].reverse()) {
+    if (/tasks_status_check/i.test(m.text)) {
+      const block = m.text.match(/tasks_status_check[\s\S]*?status\s+IN\s*\(([\s\S]*?)\)/i);
+      if (block) return [...block[1].matchAll(/'([a-z_]+)'/g)].map((x) => x[1]);
+    }
+  }
+  for (const m of migs) {
+    const block = m.text.match(/status\s+text[\s\S]*?CHECK\s*\(\s*status\s+IN\s*\(([\s\S]*?)\)/i);
+    if (block) return [...block[1].matchAll(/'([a-z_]+)'/g)].map((x) => x[1]);
+  }
+  return [];
+}
+
+async function liveVersions() {
+  const { cliClient } = require('./cli-lib');
+  const api = await cliClient();
+  const r = await api.public.getPublicVersions();
+  if (!r.ok) throw new Error(`public/versions failed: ${r.status}`);
+  // started_at is carried for chronological ordering in the generator; the drift
+  // checker compares only id/status, so the extra field is harmless there.
+  return (r.data.versions || []).map((v) => ({
+    id: v.id,
+    status: v.status,
+    started_at: v.started_at || null,
+  }));
+}
+
+// --- conceptual-diagram facts (03-drachmae-karma, 04-architecture) ----------
+//
+// Both conceptual diagrams reduce to the same shape: a feature-piece is LIVE iff
+// its backing GDS task is 'shipped'. We fetch the live status of every task id
+// the two diagrams reference (authenticated, since /tasks/:id is not public) and
+// the count of seeded achievements (for 03's "N seeded" label).
+//
+// The task ids below are the LIVE GDS ids (verified 2026-05-30), NOT the seed
+// refs — the V3 renumber (migration 021) made seed-ref R##s diverge from live
+// ids in a couple of places. In particular the bounty-AWARDING gate is the
+// "auto-confirmation flow that awards drachmae" task (#286 / live ref R67), not
+// the security-ADR-stub task that the old hand-authored .mmd loosely called
+// "R68" (#287). Each entry documents the piece it drives.
+const CONCEPTUAL_TASK_IDS = {
+  // 04-architecture (the MEMORY layer) — ADR 0024 cloneable-memory chain.
+  273: 'R54 — builder_memory store schema',
+  274: 'R55 — sync-on-ship (push)',
+  275: 'R56 — pull-on-session-start',
+  276: 'R57 — per-builder isolation + Archon audited forensic read',
+  // 03-drachmae-karma — bounty.
+  284: 'R65 — bounty payout rate card (src/bongos/security.js + /builders)',
+  286: 'R67 — auto-confirmation flow that awards drachmae (the awarding gate)',
+  282: 'R63 — vulnerability_reports table + schema',
+  // 03-drachmae-karma — karma.
+  245: 'R25 — builder-on-builder upvote/downvote on confirmed work',
+  248: 'R32 — karma boost on proposal ratification',
+  246: 'R26 — karma surfaced on profile + sortable on leaderboard',
+};
+
+// 04-architecture (the DEV BOX + box→prod flow) — where a builder's work runs
+// and how code reaches prod. Same "LIVE iff its backing GDS task is 'shipped'"
+// contract as the memory chain above; these were merged into the single
+// 04-architecture diagram (was the standalone 06-dev-box). Live ids verified
+// 2026-06-14 — the whole chain is now shipped, including 1027 + 1028. Each entry
+// documents the piece it drives in scripts/gds/gen-diagrams.js `architectureMmd`:
+//   904  — the OTB Dev Box desktop app (menu-bar/tray on-off switch)
+//   774  — the browser-only box terminal (ttyd over an outbound tunnel)
+//   897  — the per-builder sandbox live game preview on the box
+//   919  — the scoped dev-box session (box token deny-by-default)
+//   1025 — server-mediated branch publish (box uploads bundle, server pushes)
+//   859  — CI self-deploy (Actions deploys main→droplet; no key on any box)
+//   1027 — hardware-verify of the box→prod flow end-to-end (now SHIPPED)
+//   1028 — replaced the standing push PAT with a GitHub App (now SHIPPED)
+const DEV_BOX_TASK_IDS = {
+  904: 'devbox-app — desktop on-off switch',
+  774: 'browser-only box terminal (ttyd over tunnel)',
+  897: 'per-builder sandbox live preview',
+  919: 'scoped dev-box session (box token deny-by-default)',
+  1025: 'server-mediated branch publish (box uploads bundle, server pushes)',
+  859: 'CI self-deploy (Actions deploys main to the droplet)',
+  1027: 'hardware-verify the box-to-prod flow end-to-end',
+  1028: 'GitHub App hardening (replace the standing push PAT)',
+};
+
+// Count of distinct achievement ids seeded across all migrations. There is no
+// public achievements endpoint, so we read the seed INSERTs directly — the
+// cheapest reliable source. Distinct on id so a later migration that UPSERTs an
+// existing achievement (e.g. 031 corrects streak-3/streak-7) doesn't double-count.
+function seededAchievementCount(migs) {
+  const ids = new Set();
+  for (const m of migs) {
+    // Only scan the achievements seed blocks; an INSERT row looks like
+    //   ('first-ship', 'First Ship', ...
+    // We key off the INSERT INTO achievements header so we don't pick up
+    // id-shaped literals elsewhere in the file, and terminate the block at the
+    // trailing ON CONFLICT / statement-end. We deliberately do NOT terminate on
+    // the first ';' — a description string can legitimately contain one (e.g.
+    // "Hold two simultaneous claims; ship both successfully."), which would
+    // truncate the VALUES block and undercount.
+    const re = /INSERT\s+INTO\s+achievements\s*\([^)]*\)\s*VALUES([\s\S]*?)(?:\bON\s+CONFLICT\b|;\s*(?:--|$|\n\s*(?:INSERT|UPDATE|ALTER|CREATE)))/gi;
+    let block;
+    while ((block = re.exec(m.text)) !== null) {
+      // Each row's id is the first quoted literal after the row's opening paren.
+      for (const row of block[1].matchAll(/\(\s*'([a-z0-9-]+)'\s*,/gi)) ids.add(row[1]);
+    }
+  }
+  return ids.size;
+}
+
+// Repo slug ("host/owner/repo") for 04's REPO node — derived from the git
+// `origin` remote so no builder identity is hardcoded in implementation code
+// (CLAUDE.md V3.R12 rule + scripts/gds/audit-authorship.sh). Falls back to a
+// neutral placeholder if origin can't be read.
+function repoSlug(repo) {
+  try {
+    const url = execFileSync('git', ['-C', repo, 'remote', 'get-url', 'origin'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    // git@github.com:owner/repo.git  OR  https://github.com/owner/repo(.git)
+    const m =
+      url.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/) ||
+      url.match(/github\.com[:/](.+?)(?:\.git)?$/);
+    if (m) return `github.com/${m[1].replace(/^github\.com\//, '')}`;
+  } catch (_) {
+    /* no remote / not a repo — fall through */
+  }
+  return 'the project repo';
+}
+
+// Fetch live status for each conceptual task id. Authenticated (allow-unauth so
+// a 401 returns a sentinel instead of exiting the whole process via cli-lib's
+// guidance path). Returns null on ANY failure (no session, network, non-200) so
+// the generator can SKIP regenerating 03/04 rather than emit wrong data.
+async function conceptualFacts({ repo, migs }) {
+  // Reuse the caller's migrations read when provided (gatherFacts already reads
+  // them once); only fall back to a fresh read for standalone callers.
+  migs = migs || readMigrations(repo);
+  const { cliClient } = require('./cli-lib');
+  // allow-unauth so a 401 returns a sentinel instead of exiting the whole
+  // process via cli-lib's guidance path (see the loop's degrade-to-null below).
+  const api = await cliClient({ allowUnauthenticated: true });
+  // 03's pieces + 04-architecture's memory chain + its dev-box/ship-flow pieces
+  // share one fetch + one taskStatus map; any unreachable id degrades the WHOLE
+  // conceptual bundle (so 03 + 04 skip together rather than emit partial data).
+  const ALL_TASK_IDS = { ...CONCEPTUAL_TASK_IDS, ...DEV_BOX_TASK_IDS };
+  const ids = Object.keys(ALL_TASK_IDS).map(Number);
+  const status = {};
+  for (const id of ids) {
+    let s = null;
+    try {
+      const r = await api.tasks.getTasksId({ id });
+      if (r.ok) s = (r.data.task || r.data).status || null;
+    } catch (_) {
+      s = null;
+    }
+    if (s === null) {
+      // Any unreachable id degrades the whole conceptual bundle — partial data
+      // could flip a piece to the wrong state. Bail to the sentinel.
+      return null;
+    }
+    status[id] = s;
+  }
+  return {
+    taskStatus: status,
+    taskLabels: { ...ALL_TASK_IDS },
+    achievementsSeeded: seededAchievementCount(migs),
+    repoSlug: repoSlug(repo),
+  };
+}
+
+// --- convenience: gather everything ---
+async function gatherFacts({ repo }) {
+  const migs = readMigrations(repo);
+  const src = readGdsSource(repo);
+  const enum_ = rankEnum(migs);
+  return {
+    rank_enum: enum_,
+    default_rank: defaultRank(migs),
+    wired_ranks: wiredRanks(migs, src, enum_),
+    task_statuses: taskStatuses(migs),
+    versions: await liveVersions(),
+    // Conceptual-diagram facts (03 + 04). null = degraded (no session / API
+    // unreachable) → the generator SKIPS regenerating the conceptual diagrams.
+    conceptual: await conceptualFacts({ repo, migs }),
+  };
+}
+
+module.exports = {
+  stripJs,
+  stripSql,
+  readMigrations,
+  readGdsSource,
+  rankEnum,
+  defaultRank,
+  wiredRanks,
+  taskStatuses,
+  liveVersions,
+  seededAchievementCount,
+  repoSlug,
+  conceptualFacts,
+  CONCEPTUAL_TASK_IDS,
+  DEV_BOX_TASK_IDS,
+  gatherFacts,
+};

package/scripts/gds/discipline-modes.json

@@ -0,0 +1,25 @@
+{
+  "_doc": "Discipline -> operating-playbook map (task 1267). A discipline whose work is best done as a *mode of working* rather than the default claim->build->ship loop names the skill that IS its playbook here. claim.js reads this after a successful claim: if the claimed task's `discipline` has an entry, it prints the entry's `directive` so the session opens the right playbook. There is NO classification step at claim time — `discipline` is already a column on the task. This is the whole discipline-fork mechanism: one carrier (the claim the builder already runs), one data lookup, no hooks, the Conductor untouched. Absence of an entry is the default: engineer and artist are intentionally NOT listed, so their claim output is unchanged and they stay in the standard build-and-ship loop. To give a discipline its own experience later, add an entry here and write the skill — no code change in claim.js. A missing or invalid version of this file must never break a claim (claim.js fails open).",
+  "modes": {
+    "engineer": {
+      "skill": "dev",
+      "label": "Engineering session",
+      "directive": "This is an ENGINEER task. /dev is its operating playbook — the standard build loop, written down: understand the code before editing -> make the smallest correct, scoped change -> VERIFY it (smoke tests + the preview/verification workflow when observable) -> /builder-ship with real notes. Engineering is already the default way you'd work, so this is a reminder of the standard (and the autonomous-mode guardrails: be conservative, verify hard, don't wander), not a redirect. Open /dev if you want the checklist or you're running autonomously."
+    },
+    "ideator": {
+      "skill": "ideate",
+      "label": "Ideation session",
+      "directive": "This is an IDEATOR task. To work it, invoke the /ideate skill — that skill is the operating playbook for ideation, and it is the only place the experience is defined. It inverts the usual dynamic: you (the human ideator) are the creative driver and Claude is your sounding board / research arm / devil's advocate, not a content generator filing ideas on command. If no human is present (autonomous / bypass-permissions), /ideate runs a self-adversarial divergence-and-critique loop instead of dumping a fixed batch. Open /ideate now rather than working this task the default way."
+    },
+    "artist": {
+      "skill": "paint",
+      "label": "Art session",
+      "directive": "This is an ARTIST task. To work it, invoke the /paint skill — that skill is the operating playbook for art sessions, and it is the only place the experience is defined. It is show-first / low-text: Claude communicates in pictures (display the generated tile, the /art gallery at sandbox-<login>.amazonprimea.com/art, and the in-world sandbox), not paragraphs about what the pipeline did. It drives the existing pixel-art pipeline (otb-tile-generate / otb-design-review / otb-feedback-capture / art-stage.js) and keeps the locked palette + rubric sacred. If no human is present (autonomous / bypass-permissions), /paint generates, rubric-gates hard, stages passing assets to the gallery, and parks the visuals for human review. Open /paint now rather than working this task the default way; the gallery is at sandbox-<login>.amazonprimea.com/art."
+    },
+    "ui": {
+      "skill": "design",
+      "label": "UI design session",
+      "directive": "This is a UI task — interface DESIGN work (layout, wireframes, design systems, Figma / Claude-Design), split out of the pixel-art `artist` lane (ADR 0079). To work it, invoke the /design skill — the operating playbook for UI-design sessions, the only place the experience is defined. Like /paint it is show-first: communicate in mock-ups and rendered screens, not paragraphs about layout decisions — stage the change on your sandbox preview (/builder-stage) and look at the real interface before shipping. Keep the locked branding (config/branding.json) and the existing component conventions of the surface you touch (modules/status-ui, modules/hall-ui, public/game/ui). If no human is present (autonomous / bypass-permissions), produce the design, stage it for review, and park the screens rather than shipping interface changes blind. Open /design now rather than working this task the default way."
+    }
+  }
+}

package/scripts/gds/discord-channels.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+'use strict';
+
+// Archon CLI for bot-managed Discord channels (ADR 0037, task #727).
+//
+// Thin wrapper over the HTTP API so the rank gate stays SERVER-SIDE: the
+// /discord/channels/* routes re-check the caller's live builders.rank with
+// requireRank('archon'). A non-Archon session gets a 403 here, exactly as it
+// would from any other privileged command. This script never talks to Discord
+// directly — it asks the deployed bot (via the API) to do the work.
+//
+// Usage:
+//   node scripts/gds/discord-channels.js plan     # dry run: what WOULD change
+//   node scripts/gds/discord-channels.js apply     # apply docs/discord/channels.json to Discord
+//
+// The channel layout itself is edited in docs/discord/channels.json and merged
+// (rank-gated) — this command just triggers the reconcile.
+
+const { cliClient } = require('./cli-lib');
+
+async function main() {
+  const cmd = (process.argv[2] || '').toLowerCase();
+  if (cmd !== 'plan' && cmd !== 'apply') {
+    console.error('usage: node scripts/gds/discord-channels.js <plan|apply>');
+    process.exit(2);
+  }
+
+  const api = await cliClient();
+  let res;
+  if (cmd === 'plan') {
+    res = await api.discord.getDiscordChannelsPlan();
+  } else {
+    res = await api.discord.postDiscordChannelsReconcile({ body: {} });
+  }
+
+  const body = res.data || {};
+  if (res.status === 403) {
+    console.error('Refused: channel commands are Archon-only (your live rank is not archon).');
+    process.exit(1);
+  }
+  if (res.status === 503) {
+    console.error(`Bot unavailable (${body.reason}). The bot must be enabled (DISCORD_BOT_ENABLED) and connected to the guild.`);
+    process.exit(1);
+  }
+  if (res.status < 200 || res.status >= 300) {
+    console.error(`API error ${res.status}:`, JSON.stringify(body));
+    process.exit(1);
+  }
+
+  for (const w of body.warnings || []) console.warn(`warning: ${w}`);
+  if (cmd === 'plan') {
+    const ops = body.ops || [];
+    if (!ops.length) { console.log('In sync — no channel changes needed.'); return; }
+    console.log(`${ops.length} change(s) the bot would apply:`);
+    for (const op of ops) {
+      const bits = [op.op, op.name];
+      if (op.topic !== undefined) bits.push('(topic)');
+      if (op.overwrites !== undefined) bits.push('(perms)');
+      console.log('  - ' + bits.join(' '));
+    }
+  } else {
+    console.log(`Applied ${body.applied}/${body.total} change(s); ${body.failed} failed.`);
+  }
+}
+
+main().catch((err) => { console.error(err.message); process.exit(1); });

package/scripts/gds/do-api.js

@@ -0,0 +1,176 @@
+// scripts/gds/do-api.js — a thin DigitalOcean API v2 client for the control plane.
+//
+// Shared control-plane client (ADR 0111 §2, task #1943): the DO client both the
+// dev-box CLI (scripts/gds/box.js) and the instance-provisioning runner
+// (scripts/gds/provision.js) use. It lived in modules/dev-box/ historically, but
+// it is operator-CLI code (never the web tier), so it belongs in the control-plane
+// tier alongside its callers — and a module may not import a sibling module, so two
+// CLIs can only share it from here. Originally #598 (box lifecycle).
+//
+// The ONLY network module in the box-lifecycle subsystem. Everything that
+// touches DO goes through here so the rest of the code (boxes.js decisions,
+// box.js orchestration) stays testable without a live account.
+//
+// Design:
+//   - Injectable transport (`fetchImpl`) so tests pass a fake fetch and assert
+//     the request shape without hitting the network.
+//   - `dryRun` mode (the DEFAULT for the CLI): NO request is sent. Each method
+//     logs the call it WOULD make and returns a synthetic, clearly-marked
+//     result (`{ dryRun: true, ... }`) so the orchestrator's control flow runs
+//     end-to-end against a throwaway plan. This mirrors how provision-staging.sh
+//     and stale-claim-release ship runnable logic whose LIVE leg is a separate,
+//     explicit operator action.
+//   - Live mode requires a token (DO_API_TOKEN); the constructor throws clearly
+//     if asked to run live without one — it never silently no-ops a real call.
+//
+// We implement only the calls the lifecycle needs:
+//   createDroplet · getDroplet · deleteDroplet · listDroplets
+//   snapshotDroplet (action) · getAction (poll) · deleteSnapshot
+//   createDropletFromSnapshot
+
+const { JsonHttpApi, makeApiError } = require('./http-api-client');
+
+const DO_API_BASE = 'https://api.digitalocean.com/v2';
+
+const DoApiError = makeApiError('DoApiError', 'DO_API_ERROR');
+
+class DoApi extends JsonHttpApi {
+  // opts: { token, dryRun=true, fetchImpl=globalThis.fetch, base, log }
+  constructor(opts = {}) {
+    super(opts, { base: DO_API_BASE, logTag: 'DO', ErrorClass: DoApiError });
+    if (!this.dryRun && !this.token) {
+      throw new DoApiError(
+        'live DigitalOcean call requested but DO_API_TOKEN is not set — ' +
+        'export DO_API_TOKEN or run without --apply (dry-run)'
+      );
+    }
+    if (!this.dryRun && typeof this.fetchImpl !== 'function') {
+      throw new DoApiError('no fetch implementation available for live mode');
+    }
+  }
+
+  // _req (the dry-run/live request skeleton) is inherited from JsonHttpApi. DoApi
+  // uses the base error detection (non-2xx → message/id) and adds no fetch init.
+
+  // ---- droplets --------------------------------------------------------------
+
+  // image: either a base image slug (e.g. 'docker-20-04') OR a snapshot id (int).
+  async createDroplet({ name, region, size, image, userData, tags, sshKeys }) {
+    const body = {
+      name, region, size, image,
+      user_data: userData || undefined,
+      tags: tags || undefined,
+      ssh_keys: sshKeys || undefined,
+      ipv6: false,
+      monitoring: true,
+    };
+    return this._req('POST', '/droplets', body, {
+      dryRunResult: { droplet: { id: `dryrun-droplet-${name}`, status: 'new' } },
+    });
+  }
+
+  async getDroplet(dropletId) {
+    return this._req('GET', `/droplets/${dropletId}`, null, {
+      dryRunResult: { droplet: { id: dropletId, status: 'active', networks: { v4: [] } } },
+    });
+  }
+
+  async deleteDroplet(dropletId) {
+    return this._req('DELETE', `/droplets/${dropletId}`, null, { dryRunResult: { deleted: true } });
+  }
+
+  // List every droplet carrying `tag` (our fleet tag, e.g. otb-builder-box). The
+  // input to the drift reconcile (task 1289): compare these REAL droplets against
+  // the GDS box rows to find zombies (a droplet no live box claims) and ghosts (a
+  // box row whose droplet vanished). per_page=200 covers the whole fleet in one
+  // page at our scale (<100 boxes); a future larger fleet would follow
+  // links.pages.next. Returns { droplets: [...] }; dry-run returns an empty list
+  // (the reconcile builds its OWN live read client so planning still sees drift).
+  async listDroplets({ tag } = {}) {
+    const qs = tag ? `?tag_name=${encodeURIComponent(tag)}&per_page=200` : '?per_page=200';
+    return this._req('GET', `/droplets${qs}`, null, { dryRunResult: { droplets: [] } });
+  }
+
+  // ---- snapshots (via droplet actions) --------------------------------------
+
+  // Snapshot a running droplet. DO recommends powering off first for a clean
+  // snapshot; the orchestrator powers off then calls this. Returns an ACTION
+  // whose completion must be polled (getAction) before the droplet is destroyed.
+  async snapshotDroplet(dropletId, snapshotName) {
+    return this._req('POST', `/droplets/${dropletId}/actions`, { type: 'snapshot', name: snapshotName }, {
+      dryRunResult: { action: { id: `dryrun-action-${dropletId}`, status: 'completed', type: 'snapshot' } },
+    });
+  }
+
+  async powerOffDroplet(dropletId) {
+    return this._req('POST', `/droplets/${dropletId}/actions`, { type: 'power_off' }, {
+      dryRunResult: { action: { id: `dryrun-poweroff-${dropletId}`, status: 'completed' } },
+    });
+  }
+
+  async getAction(actionId) {
+    return this._req('GET', `/actions/${actionId}`, null, {
+      dryRunResult: { action: { id: actionId, status: 'completed' } },
+    });
+  }
+
+  async deleteSnapshot(snapshotId) {
+    return this._req('DELETE', `/snapshots/${snapshotId}`, null, { dryRunResult: { deleted: true } });
+  }
+
+  async createDropletFromSnapshot({ name, region, size, snapshotId, userData, tags, sshKeys }) {
+    return this.createDroplet({ name, region, size, image: snapshotId, userData, tags, sshKeys });
+  }
+
+  // Shared poll primitive behind waitForAction + settleDroplet (the box
+  // subsystem's two DO poll loops, unified per the #1092 cleanup). Calls step(i)
+  // each round; step returns { done:true, value } to stop, or a falsy value to keep
+  // polling. Returns the stopping value, or { timedOut:true } after `tries` rounds.
+  // `sleepFn` lets tests drive the loop with no real clock.
+  async _poll({ tries = 60, sleepMs = 5000, sleepFn } = {}, step) {
+    const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    for (let i = 0; i < tries; i++) {
+      const r = await step(i);
+      if (r && r.done) return r.value;
+      await sleep(sleepMs);
+    }
+    return { timedOut: true };
+  }
+
+  // Poll an action to completion. Returns true if 'completed', throws on 'errored'.
+  // sleepFn lets tests drive the loop deterministically (no real sleeping).
+  async waitForAction(actionId, { tries = 60, sleepMs = 5000, sleepFn } = {}) {
+    if (this.dryRun) return true;
+    const out = await this._poll({ tries, sleepMs, sleepFn }, async () => {
+      const { action } = await this.getAction(actionId);
+      if (action.status === 'completed') return { done: true, value: true };
+      if (action.status === 'errored') {
+        throw new DoApiError(`DO action ${actionId} errored`, { body: action });
+      }
+      return null;
+    });
+    if (out && out.timedOut) throw new DoApiError(`DO action ${actionId} did not complete in time`);
+    return out;
+  }
+
+  // Wait until a freshly-created droplet is 'active' and return its public IPv4.
+  // Lives here (alongside waitForAction) so the box subsystem's two DO poll loops
+  // share one primitive; scripts/gds/box.js calls it as a method. dry-run returns
+  // no IP (it never created a real droplet).
+  async settleDroplet(dropletId, { tries = 60, sleepMs = 5000, sleepFn } = {}) {
+    if (this.dryRun) return { ip: null };
+    const out = await this._poll({ tries, sleepMs, sleepFn }, async () => {
+      const { droplet } = await this.getDroplet(dropletId);
+      if (droplet && droplet.status === 'active') {
+        const v4 = (droplet.networks && droplet.networks.v4) || [];
+        const pub = v4.find((n) => n.type === 'public');
+        return { done: true, value: { ip: pub ? pub.ip_address : null } };
+      }
+      return null;
+    });
+    if (out && out.timedOut) throw new Error(`droplet ${dropletId} did not reach 'active' in time`);
+    return out;
+  }
+}
+
+module.exports = { DoApi, DoApiError, DO_API_BASE };