@bongos/core 1.19.1073 → 1.19.1074

package/scripts/gds/artifact-format.js

@@ -0,0 +1,203 @@
+// scripts/gds/artifact-format.js — the ONE packaging format Bongos ships code in:
+// a deterministic ustar+gzip tarball plus a compression-independent tree pin
+// (per-file sha256 + tree_sha256). Split out of package-core.js (task 1004271) so the
+// module store (ADR 0338 D1: "no second packaging format") builds and VERIFIES module
+// versions with the exact functions the core release uses — and so the always-on
+// server can read a tarball without loading package-core.js's release machinery.
+// Pure: no I/O beyond zlib/crypto, no git, no network.
+
+const zlib = require('node:zlib');
+const crypto = require('node:crypto');
+
+function sha256hex(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+// The PIN. A canonical, compression-independent digest of a packaged tree: one
+// "path\0mode\0filesha256\n" line per file, byte-sorted by path. A consumer
+// recomputes this from the unpacked tree to prove an install matches the pin.
+// `files` = [{ path, mode, sha256 }]. Modes are normalized so the pin is stable
+// regardless of the checkout's umask.
+function canonicalTreeHash(files) {
+  const lines = (files || [])
+    .map((f) => `${f.path}\u0000${normalizeMode(f.mode)}\u0000${f.sha256}`)
+    .sort();
+  return sha256hex(Buffer.from(lines.join('\n') + '\n', 'utf8'));
+}
+
+// Collapse ANY mode form — git's 100644/100755, our canonical 0000644/0000755, or a
+// raw filesystem octal string like "755" — to two canonical tar modes, keyed only on
+// the executable bit. IDEMPOTENT (normalizeMode(normalizeMode(x)) === normalizeMode(x))
+// AND exec-aware, so the tree pin reproduces byte-identically whether a consumer
+// recomputes it from the manifest's files[] (already-canonical modes) or from the
+// unpacked tree's stat() modes. Expects a STRING (git mode / canonical mode / octal).
+function normalizeMode(mode) {
+  const s = String(mode);
+  if (s === '100755' || s === '0000755' || s === '755') return '0000755';
+  const n = parseInt(s, 8);
+  if (Number.isFinite(n) && (n & 0o111)) return '0000755';
+  return '0000644';
+}
+
+// ---- a minimal, correct, DETERMINISTIC ustar+gzip writer (node-only, #686) ----
+// Deterministic (fixed mtime/uid/gid, normalized mode, sorted entries) so the same
+// source yields byte-identical bytes — a bonus over the tree_sha256 pin. Long paths
+// use the ustar name/prefix split, falling back to a GNU 'L' longname entry (read
+// by GNU tar, bsdtar/macOS, and node-tar) for the rare path that won't split.
+
+function octal(n, width) {
+  // width-1 octal digits, zero-padded, then a NUL — the classic numeric field.
+  return Buffer.from(n.toString(8).padStart(width - 1, '0').slice(-(width - 1)) + '\0', 'ascii');
+}
+
+function tarChecksum(block) {
+  let sum = 0;
+  for (let i = 0; i < 512; i++) sum += (i >= 148 && i < 156) ? 0x20 : block[i];
+  return sum;
+}
+
+// Build one 512-byte ustar header. `name`/`prefix` must already fit (<=100 / <=155).
+function ustarHeader({ name, prefix = '', mode, size, typeflag }) {
+  const h = Buffer.alloc(512, 0);
+  h.write(name, 0, 100, 'utf8');
+  octal(mode, 8).copy(h, 100);
+  octal(0, 8).copy(h, 108);   // uid
+  octal(0, 8).copy(h, 116);   // gid
+  octal(size, 12).copy(h, 124);
+  octal(0, 12).copy(h, 136);  // mtime = 0 (determinism)
+  h.write(typeflag, 156, 1, 'ascii');
+  h.write('ustar\0', 257, 6, 'ascii');
+  h.write('00', 263, 2, 'ascii');
+  if (prefix) h.write(prefix, 345, 155, 'utf8');
+  // checksum field: 6 octal digits + NUL + space, computed with the field = spaces.
+  const cksum = tarChecksum(h);
+  h.write(cksum.toString(8).padStart(6, '0').slice(-6) + '\0 ', 148, 8, 'ascii');
+  return h;
+}
+
+// Split a >100-byte path into { name<=100, prefix<=155 } at a '/' boundary, or
+// return null if no split fits (→ caller uses the GNU longname fallback).
+function splitUstarName(fullPath) {
+  const bytes = Buffer.byteLength(fullPath, 'utf8');
+  if (bytes <= 100) return { name: fullPath, prefix: '' };
+  // Find the LAST '/' such that the tail (after it) is <=100 and the head <=155.
+  for (let i = fullPath.length - 1; i > 0; i--) {
+    if (fullPath[i] !== '/') continue;
+    const prefix = fullPath.slice(0, i);
+    const name = fullPath.slice(i + 1);
+    if (Buffer.byteLength(name, 'utf8') <= 100 && Buffer.byteLength(prefix, 'utf8') <= 155) {
+      return { name, prefix };
+    }
+  }
+  return null;
+}
+
+function padTo512(buf) {
+  const rem = buf.length % 512;
+  return rem === 0 ? buf : Buffer.concat([buf, Buffer.alloc(512 - rem, 0)]);
+}
+
+// GNU longname pseudo-entry: a header (typeflag 'L', name '././@LongLink') whose
+// BODY is the full path (incl. trailing NUL), immediately followed by the real
+// file entry. Read by GNU tar, bsdtar/macOS, and node-tar.
+function gnuLongName(fullPath) {
+  const payload = Buffer.from(fullPath + '\0', 'utf8');
+  const hdr = ustarHeader({ name: '././@LongLink', mode: 0o644, size: payload.length, typeflag: 'L' });
+  return Buffer.concat([hdr, padTo512(payload)]);
+}
+
+// entries: [{ name, mode, buf }] — `name` includes the TAR_ROOT prefix. Returns a
+// gzip'd tar Buffer. Pure + deterministic given sorted entries.
+function buildTar(entries) {
+  const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+  const chunks = [];
+  for (const e of sorted) {
+    const mode = e.mode & 0o7777;
+    const split = splitUstarName(e.name);
+    if (split) {
+      chunks.push(ustarHeader({ name: split.name, prefix: split.prefix, mode, size: e.buf.length, typeflag: '0' }));
+    } else {
+      chunks.push(gnuLongName(e.name));
+      chunks.push(ustarHeader({ name: e.name.slice(0, 100), mode, size: e.buf.length, typeflag: '0' }));
+    }
+    chunks.push(padTo512(e.buf));
+  }
+  // two zero blocks terminate the archive
+  chunks.push(Buffer.alloc(1024, 0));
+  const tar = Buffer.concat(chunks);
+  return zlib.gzipSync(tar, { level: 9 });
+}
+
+
+
+// ---- the matching READER (task 1004271) -------------------------------------
+// Reads back exactly what buildTar writes — plain ustar file entries (name/prefix
+// split) and GNU 'L' longname entries — into [{ name, mode, buf }]. It is the store's
+// side of the format, so it is strict rather than permissive: any other entry type
+// (a directory, a symlink, a pax header), a size or count over the caps, a truncated
+// archive or a bad header checksum is a THROWN error, never a skipped entry. A server
+// that verifies uploads must not quietly accept a shape it did not check.
+//
+// Two entry points over one parser: readTar (sync — the CLI and tests) and
+// readTarAsync, which inflates on libuv's thread pool so a server verifying an upload
+// does not hold the event loop for the decompression. The parse itself is a single
+// linear pass over the inflated bytes.
+const DEFAULT_READ_LIMITS = { maxUnpackedBytes: 64 * 1024 * 1024, maxFiles: 5000 };
+const gunzipAsync = require('node:util').promisify(zlib.gunzip);
+
+const unreadable = (maxUnpackedBytes, e) =>
+  new Error(`not a readable gzip tarball within ${maxUnpackedBytes} bytes (${e.code || e.message})`);
+
+function readTar(tgz, { maxUnpackedBytes = DEFAULT_READ_LIMITS.maxUnpackedBytes, maxFiles = DEFAULT_READ_LIMITS.maxFiles } = {}) {
+  let tar;
+  try { tar = zlib.gunzipSync(tgz, { maxOutputLength: maxUnpackedBytes }); }
+  catch (e) { throw unreadable(maxUnpackedBytes, e); }
+  return parseTar(tar, { maxFiles });
+}
+
+async function readTarAsync(tgz, { maxUnpackedBytes = DEFAULT_READ_LIMITS.maxUnpackedBytes, maxFiles = DEFAULT_READ_LIMITS.maxFiles } = {}) {
+  let tar;
+  try { tar = await gunzipAsync(tgz, { maxOutputLength: maxUnpackedBytes }); }
+  catch (e) { throw unreadable(maxUnpackedBytes, e); }
+  return parseTar(tar, { maxFiles });
+}
+
+function parseTar(tar, { maxFiles }) {
+  const cstr = (b, from, len) => {
+    const s = b.subarray(from, from + len);
+    const z = s.indexOf(0);
+    return (z < 0 ? s : s.subarray(0, z)).toString('utf8');
+  };
+  const out = [];
+  let off = 0;
+  let longName = null;
+  while (true) {
+    if (off + 512 > tar.length) throw new Error('tarball is truncated (no end-of-archive marker)');
+    const h = tar.subarray(off, off + 512);
+    if (h.every((x) => x === 0)) break;
+    const stored = parseInt(cstr(h, 148, 8).trim(), 8);
+    if (stored !== tarChecksum(h)) throw new Error(`tar header checksum mismatch at byte ${off}`);
+    const size = parseInt(cstr(h, 124, 12).trim() || '0', 8);
+    if (!Number.isFinite(size) || size < 0) throw new Error(`bad entry size at byte ${off}`);
+    const type = String.fromCharCode(h[156] || 48);
+    const bodyStart = off + 512;
+    const bodyEnd = bodyStart + size;
+    if (bodyEnd > tar.length) throw new Error('tarball is truncated mid-entry');
+    const body = tar.subarray(bodyStart, bodyEnd);
+    off = bodyStart + size + ((512 - (size % 512)) % 512);
+    if (type === 'L') { longName = cstr(body, 0, body.length); continue; }
+    if (type !== '0' && type !== '\u0000') throw new Error(`unsupported tar entry type "${type}" — only regular files are allowed`);
+    const prefix = cstr(h, 345, 155);
+    const name = longName || (prefix ? `${prefix}/${cstr(h, 0, 100)}` : cstr(h, 0, 100));
+    longName = null;
+    out.push({ name, mode: parseInt(cstr(h, 100, 8).trim() || '0', 8), buf: Buffer.from(body) });
+    if (out.length > maxFiles) throw new Error(`tarball has more than ${maxFiles} files`);
+  }
+  return out;
+}
+
+module.exports = {
+  sha256hex, canonicalTreeHash, normalizeMode,
+  octal, tarChecksum, ustarHeader, splitUstarName, padTo512, gnuLongName, buildTar,
+  readTar, readTarAsync,
+};

package/scripts/gds/audit-authorship.sh

@@ -151,13 +151,6 @@ ALLOWLIST=(
   # hardcoded in code.
   'CODEOWNERS'
 
-  # Dev Box app distribution (#904, ADR 0044): the PUBLIC releases repo lives
-  # under the same GitHub account that owns the main repo — repo-hosting
-  # identity (same nature as provision-staging.sh above), not a builder
-  # identity. The test pins the committed config's repo string.
-  'config/devbox-app.json'
-  'tests/devbox_downloads.mjs'
-
   # This audit script's own self-reference (it documents what it's looking for).
   'scripts/gds/audit-authorship.sh'
 
@@ -173,21 +166,18 @@ ALLOWLIST=(
 
   # Test DATA that pins a real contract (task 1002640) — identity in an
   # assertion IS the contract, not a mis-attribution: owner approval RECORDS
-  # the Archon's login (gate_approvals), the terminal-URL SSRF guard validates
-  # term-<login> hostnames (box_terminal_ssrf), packaging/provisioning tests
+  # the Archon's login (gate_approvals), packaging/provisioning tests
   # exercise the real repo owner + the mirror-redaction floor. Listed per file
   # (never a blanket tests/ exclusion) so a NEW test file is still scanned.
   'tests/provision.mjs'
   'tests/package_core.mjs'
   'tests/init.mjs'
-  'tests/box_terminal_ssrf.mjs'
   'tests/gate_approvals.mjs'
   'tests/publish_reconciler.mjs'
   'tests/dev_lib.mjs'
   'tests/ship_card.mjs'
   'tests/scrubber_corpus.mjs'
   'tests/module_submissions.mjs'
-  'tests/boxes.mjs'
   'tests/provisioning_onboard_mode.mjs'
   'tests/instance_manifest.mjs'
   'tests/bongos_downloads.mjs'
@@ -199,10 +189,8 @@ ALLOWLIST=(
   'tests/currency_label.mjs'
   'tests/cloud_bongos_pack.mjs'
   'tests/bump_version.mjs'
-  'tests/box_scope_session.mjs'
   'tests/auth_inactive_builder.mjs'
   'tests/auth_anthropic_identity.mjs'
-  'modules/dev-box/app/test/unit.mjs'
 
   # The mirror-redaction floor: PRIOR_INSTANCE_FLOOR carries the prior
   # instance's owner literal precisely so packaging can SCRUB it from every

package/scripts/gds/claim.js

@@ -7,21 +7,6 @@
 // On success: prints the claim id, the task title, and the touches[] so the
 // builder knows the parallel-safety boundary they're working within.
 
-// TREE PREFLIGHT (task 1003098). A task-scoped dev box carries scripts/ and
-// src/bongos/ but not every modules/ directory, so the requires below can fail —
-// and Node's loader names only the FIRST missing one, which turned recovery into
-// guess-read-fix-repeat. This enumerates every missing requirement in one message
-// and exits before the first such require runs. It must stay ABOVE them.
-//
-// A PRE-REQUEST hard exit, like the usage banner and worktree guard: nothing has
-// been sent yet, so there is no in-flight request for cliExit to drain.
-const { action: _surfaceAction } = require('./surface.js');
-const { checkTree: _checkTree } = require('./tree-preflight.js');
-{
-  const _fault = _checkTree(__filename, { command: _surfaceAction("claim") });
-  if (_fault) { console.error(_fault); process.exit(1); }
-}
-
 const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');

package/scripts/gds/cli-lib.js

@@ -139,8 +139,8 @@ function hallBase(base = API_BASE) {
 // still be mid-close when the caller's process.exit() runs, tripping a
 // UV_HANDLE_CLOSING assertion that corrupts piped JSON stdout. Connection reuse
 // buys these one-shot processes nothing, so route requests through a dispatcher
-// with keep-alive effectively disabled (mirrors cf-tunnel.js's dispatcher
-// pattern). Degrades to the default dispatcher if undici can't be required.
+// with keep-alive effectively disabled. Degrades to the default dispatcher if
+// undici can't be required.
 //
 // task 1002734 — THIS ALONE IS NOT ENOUGH, and the measurements say so: with the
 // dispatcher wired in and undici resolving fine, `node scripts/gds/api.js GET
@@ -1069,12 +1069,11 @@ function detectWorktreeName() {
 // summary — that emitCard consumes directly.
 //
 // WHY THIS READS THE PAYLOAD AND NEVER require()s render-prefs.js. The ladder
-// lives in modules/builder-settings/render-prefs.js, and requiring it from here
-// would work on a full checkout and BREAK on a task-scoped dev box, which
-// carries scripts/ and src/bongos/ but not every modules/ directory (task
-// 1003098 — tree-preflight exists precisely to fail an entry point that reaches
-// for module code, and start.js is one). So the server resolves the rung and
-// ships the answers on `render.flags`; this function only picks them up.
+// lives in modules/builder-settings/render-prefs.js, and a CLI reaches a
+// module's logic through the server, never by require — the module may be
+// disabled on the instance, and a require would couple every CLI to one
+// module's internals. So the server resolves the rung and ships the answers on
+// `render.flags`; this function only picks them up.
 //
 // TWO SERVER SHAPES, deliberately. `render.flags` is the ladder (task 1002518);
 // `render.widgets_enabled` is the boolean that predates it. A CLI newer than the
@@ -1174,6 +1173,7 @@ module.exports = {
   repairMsysMangledPath,
   resolveQuiet,
   readSessionToken,
+  CLI_USER_AGENT,
   apiCall,
   cliExit,
   isDispatcherIncompatError,

package/scripts/gds/diagram-facts.js

@@ -174,18 +174,12 @@ const CONCEPTUAL_TASK_IDS = {
   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)
-//   1027 — hardware-verify of the box→prod flow end-to-end (now SHIPPED)
+// 04-architecture (the ship flow) — how code on a builder's machine reaches
+// prod. Same "LIVE iff its backing GDS task is 'shipped'" contract as the memory
+// chain above. Each entry documents the piece it drives in
+// scripts/gds/gen-diagrams.js `architectureMmd`:
+//   1025 — server-mediated branch publish (a checkout with no GitHub push
+//          credential uploads a bundle, the server pushes it)
 //   1028 — replaced the standing push PAT with a GitHub App (now SHIPPED)
 //
 // Every id here MUST drive a piece of the diagram. An id no consumer reads is
@@ -194,15 +188,10 @@ const CONCEPTUAL_TASK_IDS = {
 // stop 03 + 04 from regenerating at all (the failure shape task 1002667 fixed
 // for the offset case). Do NOT re-add 859 (CI self-deploy): the deploy leg is
 // the standalone AUTO-PULL of ADR 0108/0129, not a task-gated Actions job, so
-// gen-diagrams.js deliberately excludes it — see its comment at `box → prod`.
+// gen-diagrams.js deliberately excludes it — see its comment at `ship flow`.
 // Removed in task 1002674.
-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)',
-  1027: 'hardware-verify the box-to-prod flow end-to-end',
+const SHIP_FLOW_TASK_IDS = {
+  1025: 'server-mediated branch publish (a checkout with no push credential uploads a bundle, the server pushes)',
   1028: 'GitHub App hardening (replace the standing push PAT)',
 };
 
@@ -290,10 +279,10 @@ async function conceptualFacts({ repo, migs, api }) {
     // process via cli-lib's guidance path (see the loop's degrade-to-null below).
     api = await cliClient({ allowUnauthenticated: true });
   }
-  // 03's pieces + 04-architecture's memory chain + its dev-box/ship-flow pieces
+  // 03's pieces + 04-architecture's memory chain + its 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 ALL_TASK_IDS = { ...CONCEPTUAL_TASK_IDS, ...SHIP_FLOW_TASK_IDS };
   const ids = Object.keys(ALL_TASK_IDS).map(Number);
   const status = {};
   let lockedOffset = null;
@@ -360,7 +349,7 @@ module.exports = {
   repoSlug,
   conceptualFacts,
   CONCEPTUAL_TASK_IDS,
-  DEV_BOX_TASK_IDS,
+  SHIP_FLOW_TASK_IDS,
   IMPORT_ID_OFFSETS,
   gatherFacts,
 };

package/scripts/gds/do-api.js

@@ -1,15 +1,12 @@
 // 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).
+// Control-plane client (ADR 0111 §2, task #1943): the DO client the
+// instance-provisioning runner (scripts/gds/provision.js) and its teardown
+// (provision-teardown.js) use. It is operator-CLI code (never the web tier), so it
+// lives in the control-plane tier alongside its callers. Originally #598.
 //
-// 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.
+// Everything that touches DO goes through here so the provisioning code stays
+// testable without a live account.
 //
 // Design:
 //   - Injectable transport (`fetchImpl`) so tests pass a fake fetch and assert
@@ -23,10 +20,8 @@
 //   - 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
+// We implement only the calls provisioning needs:
+//   createDroplet · getDroplet · deleteDroplet · settleDroplet (poll to active)
 
 const { JsonHttpApi, makeApiError } = require('./http-api-client');
 
@@ -54,7 +49,7 @@ class DoApi extends JsonHttpApi {
 
   // ---- droplets --------------------------------------------------------------
 
-  // image: either a base image slug (e.g. 'docker-20-04') OR a snapshot id (int).
+  // image: a base image slug (e.g. 'ubuntu-24-04-x64').
   async createDroplet({ name, region, size, image, userData, tags, sshKeys }) {
     const body = {
       name, region, size, image,
@@ -79,53 +74,9 @@ class DoApi extends JsonHttpApi {
     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.
+  // Poll primitive behind settleDroplet (#1092). 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)));
@@ -137,26 +88,8 @@ class DoApi extends JsonHttpApi {
     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).
+  // 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 () => {

package/scripts/gds/doc-cli-guard.js

@@ -41,6 +41,8 @@ const DOC_CLI_ALLOW = new Map([
     'art-stage.js ships with the art-pipeline HOST module, which publish-manifest.js excludes from core — absent from a core-only checkout by design; the skill says so inline.'],
   ['.claude/skills/otb-tile-generate/SKILL.md::scripts/gds/art-stage.js',
     'same as paint/SKILL.md — the art staging CLI travels with the excluded art-pipeline module, not the portable core.'],
+  ['docs/session-logs/2026-09-10-task-1003507-the-box-that-could-not-be-reaped.md::scripts/gds/box.js',
+    'a dated session log — the historical record, never rewritten — of work on a CLI the dev-box removal deleted (task 1003893); it describes what was run then, not what to run now.'],
 ]);
 
 // `node scripts/gds/foo.js` … up to the end of the line/segment, so the flags that

package/scripts/gds/doctor.js

@@ -167,7 +167,7 @@ function checkToolchain() {
 // Check 3 — Git plumbing
 // --------------------------------------------------------------------------
 // Pure verdict for the hooks gate, extracted so the truth table is testable
-// (tests/doctor_hooks.mjs) — the box-auth-check `decideBoxAuth` precedent.
+// (tests/doctor_hooks.mjs).
 //
 // `.husky/` is INSTANCE topology, not shipped in the portable core (README
 // "Secrets scanning"). So its absence is not a builder error: it means ADR 0043