@bongos/core 1.17.0

package/scripts/gds/api.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// scripts/gds/api.js — cross-platform GDS API caller (#686).
+//
+// Replaces the bash `TOKEN=$(python3 -c ...)` + `curl ... | python3 -m json.tool`
+// (+ `jq`) pattern that skill command-blocks used — that pattern breaks on
+// Windows (no python3/curl/jq by default, and `$(...)` is bash-only). node is
+// the project's guaranteed runtime, and cli-lib.apiCall already resolves the
+// session token + API base, so there is no manual token extraction here.
+//
+// Usage:
+//   node scripts/gds/api.js GET  /api/gds/inbox
+//   node scripts/gds/api.js POST /api/gds/blockers/5/resolve --body '{"resolution_note":"fixed in #690"}'
+//   node scripts/gds/api.js POST /api/gds/security/reports   --body-file report.json
+//   echo '{"verdict":"promote"}' | node scripts/gds/api.js PATCH /api/gds/inbox/12 --body-file -
+//
+// The HTTP status goes to STDERR ("POST /path → 201"); the pretty-printed JSON
+// body goes to STDOUT, so `... | node -e ...` style piping stays clean. Exit 0
+// on a 2xx, 1 on any non-2xx or transport error, 2 on bad invocation.
+
+const fs = require('node:fs');
+const { cliClient, arg, isBoxScope, printBoxScopeGuidanceAndExit } = require('./cli-lib');
+
+
+(async () => {
+  const method = (process.argv[2] || '').toUpperCase();
+  const urlPath = process.argv[3];
+  if (!method || !urlPath || !urlPath.startsWith('/')) {
+    console.error("usage: node scripts/gds/api.js <METHOD> <path> [--body '<json>' | --body-file <file|->]");
+    process.exit(2);
+  }
+
+  // Resolve an optional JSON request body. `--body-file -` reads stdin (the
+  // robust way to pass a body with awkward characters without shell quoting).
+  let body = null;
+  const bodyFile = arg('--body-file');
+  const bodyInline = arg('--body');
+  try {
+    let raw = null;
+    if (bodyFile != null) raw = bodyFile === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(bodyFile, 'utf8');
+    else if (bodyInline != null) raw = bodyInline;
+    if (raw != null && raw.trim()) body = JSON.parse(raw);
+  } catch (e) {
+    console.error(`api: could not read/parse JSON body: ${e.message}`);
+    process.exit(2);
+  }
+
+  let res;
+  try {
+    // allowUnauthenticated so a 401 renders as a normal status row + exit 1
+    // (clear error) instead of the cli-lib global "run setup" short-circuit.
+    // Generic passthrough tool: the client's baseUrl is the versioned API prefix
+    // (/api/bongos/v1), so strip a legacy /api/gds|/api/bongos[/v1] prefix off the
+    // caller-supplied path and route the remainder through the escape hatch — no
+    // generated method exists for an arbitrary runtime path.
+    const api = await cliClient({ allowUnauthenticated: true });
+    const relPath = urlPath.replace(/^\/api\/(?:bongos\/v1|bongos|gds)/, '');
+    res = await api.request(method, relPath, body != null ? { body } : {});
+  } catch (e) {
+    console.error(`api: request failed: ${e.message}`);
+    process.exit(1);
+  }
+  console.error(`${method} ${urlPath} → ${res.status}`);
+  // task 1501: on a dev box the baked session is box-scoped (ADR 0053) and every
+  // non-bootstrap call (e.g. /me, /inbox) returns 403 box_scope. We pass
+  // allowUnauthenticated above (so a 401 stays a plain error, not the setup
+  // short-circuit), which ALSO suppresses apiCall's own box_scope guidance — so
+  // surface it here. Without this the raw {error:'box_scope'} body was dumped and
+  // rank-gated skills (/idea-triage, /blocker-review, …) read the missing `rank`
+  // as "pre-rank passthrough" and silently did nothing (reported an empty inbox
+  // on a dev box). The guided message tells the builder to /builder-reauth.
+  if (isBoxScope(res)) {
+    printBoxScopeGuidanceAndExit(); // prints the re-auth guidance + exit(10)
+  }
+  if (res.data !== undefined && res.data !== null) {
+    console.log(JSON.stringify(res.data, null, 2));
+  }
+  process.exit(res.ok ? 0 : 1);
+})();

package/scripts/gds/architect-audit.js

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+// MAS Phase 5 (#459) — the Architect.
+//
+// A bounded, first-principles audit of a DEFINED SCOPE. Unlike the Grader
+// (per-ship gate) and the Conductor (per-prompt hook), the Architect runs
+// INFREQUENTLY on an explicit scope — "bounded ferocity, not constant churn."
+// It applies Musk's engineering algorithm (deletion emphasized), thinks in
+// first principles, and is not afraid to delete things. It produces:
+//   1. a written audit at docs/audits/<scope-slug>-<date>.md, and
+//   2. seed ideas filed to idea_inbox (tagged 'architect') that feed the next
+//      version's planning session.
+//
+// Model: OPUS. The one MAS agent that is NOT cross-family Sonnet — this is
+// judgment + design, not adversarial verification, and it runs rarely, so the
+// cost is bounded (CLAUDE.md §2: audits + planning + design = Opus).
+//
+// The subagent stays READ-ONLY (it returns structured JSON); this CLI does the
+// side effects (write doc, file ideas) — deterministic + auditable, mirroring
+// the grader pattern. The subagent inherits OTB_SUBAGENT=1 via grader.run-
+// Subagent, so the Conductor never fires inside it.
+//
+// Usage:
+//   node scripts/gds/architect-audit.js --scope "<name>" --paths "glob1,glob2,..." \
+//        [--version GDS-V3] [--dry-run]
+//
+//   --dry-run  do everything EXCEPT writing the doc + filing ideas (prints the
+//              audit + what it would file). NOTE: the Opus subagent call still
+//              runs (~1-5 min, real API cost) — dry-run only skips the side
+//              effects (doc write + inbox filing), not the expensive audit.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { apiCall, cliClient, arg } = require('./cli-lib');
+const grader = require('../../modules/grading/grader');
+const llmCache = require('../../src/bongos/llm-cache'); // System 5 (task 1360): cache identical audits over an unchanged tree
+const { branding } = require('../../src/branding');
+
+// The instance's project name for the Architect's identity line, so a non-OTB
+// Cloud Bongos instance audits ITS OWN project instead of a hardcoded "Off the
+// Boats" (ADR 0062 §3/§5; the branding contract's llmProjectName field). Resolved
+// once; falls back to a neutral phrase if branding fails so the audit never crashes.
+const LLM_PROJECT = (() => {
+  try { return branding().llmProjectName || 'this project'; }
+  catch { return 'this project'; }
+})();
+llmCache.setApiFallback(apiCall); // task 1381: this runs on a builder machine (no DB pool) → reach the cache via the GDS API
+
+// The Architect's deliberate model choice: Opus (judgment + design + planning,
+// per CLAUDE.md §2). Kept as its OWN literal, NOT coupled to the grader's
+// ASSUMED_BUILDER_MODEL — those are two distinct decisions (the grader constant
+// means "what the builder-under-review is assumed to use", to pick a
+// cross-family grader; this is "what the Architect thinks with"). They happen
+// to coincide today; they should be free to diverge.
+const ARCHITECT_MODEL = 'claude-opus-4-7';
+const CONTEXT_CHAR_CAP = 400_000;
+const TIMEOUT_MS = 600_000; // 10 min — a deep audit over a lot of context
+const VALID_KINDS = new Set([
+  'feature', 'bug', 'infra', 'refactor', 'spike', 'learning-capture',
+  'cleanup', 'decision', 'blocker-resolution', 'unclassified',
+]);
+
+// ---------- pure helpers (exported for tests) ----------
+
+function slug(scope) {
+  return String(scope || '')
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60) || 'audit';
+}
+
+function pickValidKind(kind) {
+  return VALID_KINDS.has(kind) ? kind : 'unclassified';
+}
+
+// Normalize + validate the subagent's seed_ideas into filable rows. Drops
+// anything without a usable title; coerces kind into the valid set.
+function validateSeedIdeas(raw) {
+  if (!Array.isArray(raw)) return [];
+  const out = [];
+  for (const it of raw) {
+    if (!it || typeof it !== 'object') continue;
+    const title = typeof it.title === 'string' ? it.title.trim() : '';
+    if (!title) continue;
+    out.push({
+      title: title.slice(0, 200),
+      kind: pickValidKind(it.kind),
+      body_md: typeof it.body_md === 'string' ? it.body_md : '',
+    });
+  }
+  return out;
+}
+
+const PROMPT_HEADER = `You are the **Architect** — the first-principles design auditor for the ${LLM_PROJECT} project. You are not a code reviewer (the Grader panel does that per-ship) and not a watcher (the Conductor does that per-prompt). You run rarely, on a bounded scope, and your job is to make the system SIMPLER and more correct at the level of structure and requirements — then hand the next version's planning a concrete set of seed ideas.
+
+Apply **Musk's engineering algorithm, IN ORDER, with deletion emphasized**:
+
+1. **Make the requirements less dumb.** Question every requirement and assumption in this scope — especially ones that came from smart people, including past-you. Whose requirement is each? Is it still true? What would you NOT build if starting today?
+2. **DELETE.** The most important step. What code / files / abstractions / config / process in this scope can be removed outright? Be aggressive: "if you're not adding ~10% of it back later, you didn't delete enough." Name specific files, functions, exports, options, layers. Estimate the LOC each deletion removes.
+3. **Simplify** what survives deletion — and ONLY what survives. Never polish a thing that should not exist. Collapse duplication (note: this codebase has had repeated copy-paste-drift findings; hunt for it), flatten needless indirection, unify near-identical code paths into one.
+4. **Accelerate** the build/ship/feedback cycle for this scope. What's slow, manual, or repeated that shouldn't be?
+5. **Automate** — LAST. Only automate things that have proven they should exist and won't keep changing.
+
+Think in first principles: reason from what the system must DO, not from what it currently IS. Be specific and unsentimental — "not afraid to delete things." Vague advice ("improve modularity") is useless; name the file, the function, the deletion, the consolidation.
+
+Your output has two parts:
+- **audit_md**: a thorough markdown audit. Required sections: "## Summary" (3-6 lines, the headline calls), "## 1. Requirements questioned", "## 2. Delete" (the heart — specific removals + LOC estimates), "## 3. Simplify", "## 4. Accelerate", "## 5. Automate", and "## The 10% honesty check" (what, if anything, you'd expect to add back — if nothing, you didn't cut deep enough; say so). Cite real file paths and symbols throughout.
+- **seed_ideas**: 3-8 CONCRETE, task-able proposals for the next version, each derived from the audit. Each: { "title": "<imperative, task-sized>", "kind": "<feature|refactor|cleanup|infra|decision|spike>", "body_md": "<what + why + rough scope + which files>" }. These get filed to the planning inbox — make them actionable, not aspirational.
+
+You have a Read tool — use it to pull any file in the scope (or adjacent to it) that you need to judge a deletion or consolidation safely. Do NOT edit files, do NOT run tests, do NOT call the network.
+
+Return ONLY JSON — no prose before/after, no markdown fences:
+{
+  "audit_md": "<the full markdown audit>",
+  "seed_ideas": [ { "title": "...", "kind": "...", "body_md": "..." }, ... ]
+}`;
+
+function buildPrompt({ scope, fileList, fileBlocks, version }) {
+  const lines = [PROMPT_HEADER, '', '---', `## Audit scope: ${scope}`, ''];
+  if (version) lines.push(`Seed ideas will be filed for planning under: ${version}`, '');
+  lines.push(`### Files in scope (${fileList.length})`, '');
+  for (const f of fileList) lines.push(`- ${f.path}  (${f.loc} lines)`);
+  lines.push('', '---', '## File contents', '');
+  lines.push(fileBlocks);
+  lines.push('', '---', 'Now audit. Lead with deletion. Be specific. Output ONLY the JSON object.');
+  return lines.join('\n');
+}
+
+// ---------- plumbing ----------
+
+function git(args) {
+  try {
+    return execFileSync('git', args, { encoding: 'utf8', timeout: 8000, stdio: ['ignore', 'pipe', 'ignore'] });
+  } catch (_) {
+    return '';
+  }
+}
+
+function repoRoot() {
+  return git(['rev-parse', '--show-toplevel']).trim() || process.cwd();
+}
+
+// Resolve comma-separated globs/paths to a deduped file list via git, honoring
+// .gitignore. Includes BOTH tracked files and untracked-but-not-ignored ones
+// (--others --exclude-standard), so a brand-new file in the scope — e.g. the
+// Architect auditing its own freshly-written, not-yet-committed code — isn't
+// invisible to the audit.
+function resolvePaths(spec, root) {
+  const globs = String(spec || '').split(',').map((s) => s.trim()).filter(Boolean);
+  const set = new Set();
+  for (const g of globs) {
+    const tracked = git(['-C', root, 'ls-files', '--', g]);
+    const untracked = git(['-C', root, 'ls-files', '--others', '--exclude-standard', '--', g]);
+    for (const f of (tracked + '\n' + untracked).split('\n').map((s) => s.trim()).filter(Boolean)) set.add(f);
+  }
+  return [...set];
+}
+
+// Read files up to the context cap; past it, list the path without contents
+// (the subagent can Read it on demand).
+function gatherContext(files, root) {
+  const fileList = [];
+  const blocks = [];
+  let used = 0;
+  for (const rel of files) {
+    let content = '';
+    try { content = fs.readFileSync(path.join(root, rel), 'utf8'); } catch (_) { continue; }
+    const loc = content.split('\n').length;
+    fileList.push({ path: rel, loc });
+    if (used + content.length > CONTEXT_CHAR_CAP) {
+      blocks.push(`### ${rel}\n[not inlined — over the context cap; Read it on demand]\n`);
+      continue;
+    }
+    used += content.length;
+    blocks.push(`### ${rel}\n\`\`\`\n${content}\n\`\`\`\n`);
+  }
+  return { fileList, fileBlocks: blocks.join('\n') };
+}
+
+
+async function main() {
+  const args = process.argv.slice(2);
+  const scope = arg('--scope', args);
+  const paths = arg('--paths', args);
+  const version = arg('--version', args) || 'GDS-V3';
+  const dryRun = args.includes('--dry-run');
+
+  if (!scope || !paths) {
+    console.error('Usage: architect-audit.js --scope "<name>" --paths "glob1,glob2,..." [--version GDS-V3] [--dry-run]');
+    process.exit(2);
+  }
+
+  const root = repoRoot();
+  const files = resolvePaths(paths, root);
+  if (files.length === 0) {
+    console.error(`No files matched --paths "${paths}". Use git-tracked paths/globs.`);
+    process.exit(2);
+  }
+
+  const { fileList, fileBlocks } = gatherContext(files, root);
+  const prompt = buildPrompt({ scope, fileList, fileBlocks, version });
+
+  console.log(`🏛  Architect audit — scope "${scope}"`);
+  console.log(`   ${fileList.length} files (${fileList.reduce((a, f) => a + f.loc, 0)} lines), model=${ARCHITECT_MODEL}, version=${version}${dryRun ? '  [DRY RUN]' : ''}`);
+  console.log('   thinking (first-principles audit — this is one big Opus call, ~1-5 min)...');
+
+  let parsed;
+  try {
+    // System 5 (task 1360): cache scoped to the git tree-hash of the in-scope
+    // files — the highest-rerun-value model call (nightly audits re-process an
+    // unchanged main). An unchanged tree → a $0 replay of the prior audit.
+    const scopeSha = llmCache.scopeShaFor(fileList.map((f) => f.path), { cwd: root });
+    const cache = llmCache.makeCacheSpec({ prompt, model: ARCHITECT_MODEL, task_type: 'architect-audit', scope_sha: scopeSha });
+    const { stdout, cached } = await grader.runSubagentCached({ prompt, opts: { model: ARCHITECT_MODEL, timeoutMs: TIMEOUT_MS, cwd: root }, cache });
+    if (cached) console.log('   ⚡ cache hit — replayed a prior identical audit at $0 (tree unchanged since).');
+    const result = grader.extractAssistantResult(stdout);
+    parsed = grader.extractJson(typeof result === 'string' ? result : JSON.stringify(result));
+  } catch (err) {
+    console.error('Architect subagent failed:', err && err.message ? err.message : err);
+    process.exit(1);
+  }
+  if (!parsed || typeof parsed.audit_md !== 'string') {
+    console.error('Architect returned no usable audit_md.');
+    process.exit(1);
+  }
+
+  const seeds = validateSeedIdeas(parsed.seed_ideas);
+  const date = new Date().toISOString().slice(0, 10);
+  const auditSlug = slug(scope);
+  const relDoc = path.join('docs', 'audits', `${auditSlug}-${date}.md`);
+
+  // Assemble the doc (header + the subagent's audit_md).
+  const header = [
+    `# Architecture Audit — ${scope}`,
+    '',
+    `- **Date:** ${date}`,
+    `- **Auditor:** the Architect (MAS Phase 5 — ADR 0024)`,
+    `- **Model:** ${ARCHITECT_MODEL}`,
+    `- **Scope (${fileList.length} files):** ${fileList.map((f) => f.path).join(', ')}`,
+    `- **Seed ideas filed:** see idea_inbox (source=architect-audit), tagged for ${version}`,
+    '',
+    '> Generated by `scripts/gds/architect-audit.js`. The Architect applies Musk\'s algorithm (delete → simplify → accelerate → automate) from first principles. Seed ideas below feed the next version\'s planning session.',
+    '',
+    '---',
+    '',
+  ].join('\n');
+  const docBody = header + parsed.audit_md.trim() + '\n';
+
+  if (dryRun) {
+    console.log(`\n[DRY RUN] would write ${relDoc} (${docBody.length} chars)`);
+    console.log(`[DRY RUN] would file ${seeds.length} seed idea(s):`);
+    for (const s of seeds) console.log(`   - [${s.kind}] ${s.title}`);
+    console.log('\n--- audit_md preview (first 1600 chars) ---\n');
+    console.log(parsed.audit_md.slice(0, 1600));
+    process.exit(0);
+  }
+
+  // Write the audit doc.
+  fs.mkdirSync(path.join(root, 'docs', 'audits'), { recursive: true });
+  fs.writeFileSync(path.join(root, relDoc), docBody);
+  console.log(`\n📜 wrote ${relDoc}`);
+
+  // File the seed ideas to the planning inbox. Payload mirrors capture.js
+  // (POST /api/gds/inbox): { title, body_md, kind, suggested_version }.
+  // Provenance (which audit produced it) is folded into body_md.
+  let filed = 0;
+  const api = await cliClient();
+  for (const s of seeds) {
+    const r = await api.inbox.postInbox({
+      body: {
+        title: s.title,
+        kind: s.kind,
+        body_md: `${s.body_md}\n\n— filed by the Architect from audit \`${relDoc}\` (scope: ${scope}).`,
+        suggested_version: version,
+      },
+    });
+    if (r.ok) { filed++; console.log(`   📥 #${r.data?.idea?.id ?? '?'} [${s.kind}] ${s.title}`); }
+    else console.error(`   ✗ failed to file "${s.title}" (${r.status})`);
+  }
+  console.log(`\n🏛  Architect audit complete — ${relDoc} + ${filed}/${seeds.length} seed idea(s) filed for ${version}.`);
+}
+
+if (require.main === module) {
+  main().catch((err) => { console.error('Architect error:', err && err.message ? err.message : err); process.exit(1); });
+}
+
+module.exports = { slug, pickValidKind, validateSeedIdeas, buildPrompt, PROMPT_HEADER };

package/scripts/gds/art-stage.js

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+// scripts/gds/art-stage.js — after the art pipeline writes modules/art-pipeline/generated/tiles/,
+// rebuild the atlas the game client loads and surface it on the builder's own
+// sandbox live preview (ADR 0044/0052) in ONE command (#1067). Today the loop is
+// generate -> manually rebuild the atlas -> manually restart -> manually refresh;
+// this collapses the last three into one step (and #1065's auto-reload then
+// refreshes the open tab on its own).
+//
+// Internal-track tooling. It does NOT regenerate art (generation costs $ and is a
+// separate, reviewed step), does NOT touch prod, and does NOT commit anything.
+//
+//   node scripts/gds/art-stage.js                 # rebuild atlas + surface on the sandbox
+//   node scripts/gds/art-stage.js --no-build      # skip the atlas rebuild, just restart + print
+//   node scripts/gds/art-stage.js --tiles "a b c" # label the affected tiles explicitly
+//
+// On a BOX the preview serves /workspace (box-game-preview.service), but a Claude
+// session edits a git worktree, so we copy the rebuilt public/assets/tiles into
+// /workspace before restarting (self-contained; does not depend on the #1068 ship
+// gate's worktree sync). It deliberately does NOT write the sandbox-stage REVIEW
+// marker — surfacing art for a look is not the same as recording a ship sign-off.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { execFileSync } = require('node:child_process');
+const sandbox = require('./sandbox-stage');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const BOX_SERVED_ROOT = '/workspace';
+const PY = process.env.PYTHON || 'python3';
+const HEALTH_TIMEOUT_MS = 90_000;
+const HEALTH_POLL_MS = 2_000;
+
+// Rebuild public/assets/tiles + the content-hashed atlas from modules/art-pipeline/generated/tiles/.
+// build_tilesheet.py copies the per-tile PNGs and calls build_atlas at its tail.
+function rebuildAtlas(deps = {}) {
+  const run = deps.execFileSync || execFileSync;
+  run(PY, [path.join(REPO_ROOT, 'modules/art-pipeline/pipeline/build_tilesheet.py')], { cwd: REPO_ROOT, stdio: 'inherit' });
+}
+
+// On a box, the preview serves /workspace/public, not the session worktree. Copy
+// the rebuilt tiles tree across so the sandbox shows the new art. No-op when the
+// session checkout IS the served root (running directly in /workspace, or a
+// laptop where the local preview serves the worktree). Best-effort: returns
+// { copied, reason? }.
+function copyAtlasToServed(deps = {}) {
+  const f = deps.fs || fs;
+  const servedRoot = deps.servedRoot || BOX_SERVED_ROOT;
+  const repoRoot = deps.repoRoot || REPO_ROOT;
+  if (path.resolve(repoRoot) === path.resolve(servedRoot)) return { copied: false, reason: 'session checkout is the served checkout' };
+  const from = path.join(repoRoot, 'public/assets/tiles');
+  const to = path.join(servedRoot, 'public/assets/tiles');
+  if (!f.existsSync(from) || !f.existsSync(servedRoot)) return { copied: false, reason: 'no served checkout / no tiles to copy' };
+  try {
+    f.cpSync(from, to, { recursive: true });
+    return { copied: true, to };
+  } catch (e) {
+    return { copied: false, reason: e.message };
+  }
+}
+
+// The tiles this run touched: an explicit --tiles list (the orchestrator knows
+// the family members) or a git diff of public/assets/tiles (standalone runs).
+function affectedTiles(explicit, deps = {}) {
+  if (explicit && explicit.trim()) return explicit.trim().split(/\s+/);
+  const run = deps.execFileSync || execFileSync;
+  try {
+    const out = run('git', ['status', '--porcelain', '--', 'public/assets/tiles'], { cwd: deps.repoRoot || REPO_ROOT, encoding: 'utf8' });
+    return out.split('\n').map((l) => l.slice(3).trim()).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+async function waitHealthy(healthUrl, deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  const deadline = Date.now() + (deps.timeoutMs || HEALTH_TIMEOUT_MS);
+  while (Date.now() < deadline) {
+    try {
+      const res = await fetchImpl(healthUrl, { signal: AbortSignal.timeout(5_000) });
+      if (res.status < 500) return true;
+    } catch { /* keep polling */ }
+    await new Promise((r) => setTimeout(r, deps.pollMs || HEALTH_POLL_MS));
+  }
+  return false;
+}
+
+function printSurfacedBlock(url, tiles, log = console.log) {
+  const bar = '─'.repeat(64);
+  log('');
+  log(bar);
+  log('  🎨 NEW ART IS LIVE ON YOUR SANDBOX');
+  log('');
+  log(`      ${url}`);
+  log('');
+  if (tiles.length) log(`  Affected: ${tiles.join(', ')}`);
+  log('  Open the link to see it in-game. (With the auto-reload from task 1065,');
+  log('  an already-open tab refreshes itself.)');
+  log(bar);
+  log('');
+}
+
+async function main(argv = process.argv.slice(2), deps = {}) {
+  const noBuild = argv.includes('--no-build');
+  const tilesArg = (() => { const i = argv.indexOf('--tiles'); return i >= 0 ? argv[i + 1] : ''; })();
+  const log = deps.log || console.log;
+
+  if (!noBuild) {
+    log('Rebuilding the atlas from modules/art-pipeline/generated/tiles/ ...');
+    rebuildAtlas(deps);
+  }
+
+  const ctx = (deps.resolvePreviewContext || sandbox.resolvePreviewContext)(deps);
+  if (!ctx) {
+    log('Atlas rebuilt into public/assets/tiles/. No sandbox here to surface it on');
+    log('(not a dev box, and this clone has no local game preview).');
+    return { ok: true, surfaced: false, reason: 'no sandbox' };
+  }
+  if (!ctx.url) {
+    log('Atlas rebuilt. This box is on the quick tunnel (no preview hostname) — no sandbox URL to open (ADR 0044).');
+    return { ok: true, surfaced: false, reason: 'no preview URL' };
+  }
+
+  if (ctx.kind === 'box') {
+    const c = copyAtlasToServed(deps);
+    if (c.copied) log(`  copied the rebuilt tiles into ${deps.servedRoot || BOX_SERVED_ROOT} so the sandbox serves them`);
+    else log(`  (atlas copy skipped: ${c.reason})`);
+  }
+
+  log(`Restarting the ${ctx.kind} preview to pick up the new atlas...`);
+  try {
+    ctx.restart(deps);
+  } catch (e) {
+    log(`  could not restart the preview (${e.message}); the atlas is rebuilt — restart manually to see it.`);
+    return { ok: false, surfaced: false, reason: e.message };
+  }
+  const healthy = await waitHealthy(ctx.healthUrl, deps);
+  if (!healthy) {
+    log('  preview did not come back healthy in time — check its logs; the atlas is rebuilt.');
+    return { ok: false, surfaced: false, reason: 'preview unhealthy' };
+  }
+  printSurfacedBlock(ctx.url, affectedTiles(tilesArg, deps), log);
+  return { ok: true, surfaced: true, url: ctx.url };
+}
+
+module.exports = { rebuildAtlas, copyAtlasToServed, affectedTiles, waitHealthy, main };
+
+if (require.main === module) {
+  main().then((r) => process.exit(r && r.ok === false ? 1 : 0)).catch((e) => {
+    console.error('art-stage error:', e.message);
+    process.exit(1);
+  });
+}