@bongos/core 1.17.1 → 1.17.3

package/migrations/instance/182_gdsv4_bongos_consolidation.sql

@@ -1,132 +0,0 @@
--- Migration 182 — Consolidate GDS-V4 into BONGOS-V1 + split out the Bongos desktop app
--- ============================================================================
--- Archon-directed project cleanup, 2026-07-02 (task 1709, ADR 0103; with Lars).
---
--- GDS-V4 and BONGOS-V1 were two parallel internal / Cloud-Bongos versions with
--- no clean divide. This migration makes BONGOS-V1 the single go-forward internal
--- (Cloud Bongos platform) version, carries GDS-V4's still-relevant open work
--- into it, splits the Bongos DESKTOP APP into its own goal, prunes superseded
--- work, and freezes GDS-V4.
---
--- REVERSIBLE by construction: no destructive drops — only status / version_id /
--- goal_id / one dependency-edge mutations. The exact before-state is snapshotted
--- in the task-1709 session notes. See ADR 0103 for the full rationale + the
--- ADR-0095 (grep-over-embeddings) decision that retires the C1 recall arm.
---
--- Idempotency: migrate.sh applies each numbered migration once; the goal INSERT
--- is additionally NOT-EXISTS-guarded so a manual re-run cannot double-create it.
--- ============================================================================
-
-BEGIN;
-
--- 1. Create the "Bongos desktop app" goal under BONGOS-V1 and reparent the app
---    tasks (mascot/brand, branded download + auto-update, the cloudbongos.com
---    landing/download page, the feedback-capture app, the absorbed Dev Box
---    switch). scope_modules stays empty until the code carve (bongos-app/ ->
---    modules/bongos-app/) creates the module, at which point the goal is scoped
---    to it. See ADR 0087 (the app absorbs Dev Box).
-DO $$
-DECLARE app_goal_id bigint;
-BEGIN
-  SELECT id INTO app_goal_id
-    FROM goals
-   WHERE version_id = 'BONGOS-V1' AND title = 'Bongos desktop app'
-   LIMIT 1;
-
-  IF app_goal_id IS NULL THEN
-    INSERT INTO goals (version_id, title, description, scope_modules, created_by, status)
-    VALUES (
-      'BONGOS-V1',
-      'Bongos desktop app',
-      'The Cloud Bongos DESKTOP APP (bongos-app/): a Zoom-style feedback-capture '
-      || 'walkthrough tool that produces one model-agnostic prompt bundle for a coding '
-      || 'agent, and the umbrella app that absorbs the Dev Box switch (ADR 0045/0072/0087). '
-      || 'Distinct from the Cloud Bongos PLATFORM (the GDS engine, modules, grader, hosting). '
-      || 'Covers: mascot/brand (Bongo Buddha), branded download + auto-update, the '
-      || 'cloudbongos.com landing/download page, and the dev-box desktop client. The code '
-      || 'carve bongos-app/ -> modules/bongos-app/ is tracked as a task under this goal.',
-      '{}',
-      1,
-      'open'
-    )
-    RETURNING id INTO app_goal_id;
-  END IF;
-
-  -- App tasks currently in GDS-V4: rebind version AND attach to the app goal.
-  --   1523 interactive mascot · 1294 devbox-app go-live bump ·
-  --   1463 devbox-app build workflow · 1484 dev-box host-key / app re-pin
-  UPDATE tasks
-     SET version_id = 'BONGOS-V1', goal_id = app_goal_id, updated_at = now()
-   WHERE id IN (1523, 1294, 1463, 1484)
-     AND version_id = 'GDS-V4';
-
-  -- App tasks already in BONGOS-V1: attach to the app goal.
-  --   1311 branded download + auto-update · 1682/1700/1701 Bongo Buddha anim ·
-  --   1702 cloudbongos.com landing/download page
-  UPDATE tasks
-     SET goal_id = app_goal_id, updated_at = now()
-   WHERE id IN (1311, 1682, 1700, 1701, 1702)
-     AND version_id = 'BONGOS-V1';
-END $$;
-
--- 2. Abandon 19 superseded tasks:
---      C1 recall/embeddings arm (939,962,966-971,1221) — retired by ADR 0095's
---        grep-over-embeddings decision (Anthropic + Sourcegraph removed embedding
---        indexes; the endorsed path is meaning-in-source, tracked separately).
---      Old V3.R## grader tasks (201,202,242,292,388,490,492) — superseded by the
---        shipped 4-worker grader panel + ADR 0089.
---      T-NNN task-ref migration (753,754,755) — the current hall-link convention
---        already works and is enforced.
-UPDATE tasks
-   SET status = 'abandoned', updated_at = now()
- WHERE id IN (939,962,966,967,968,969,970,971,1221,
-              201,202,242,292,388,490,492,
-              753,754,755)
-   AND version_id = 'GDS-V4'
-   AND status IN ('backlog', 'ready');
-
--- 3. Sever the 758 -> 753 dependency edge. 753 (T-NNN ADR) is being abandoned;
---    758 ("document the hall as the canonical doc surface") is kept and must not
---    be left permanently unclaimable (DEPS_NOT_SHIPPED) by a dead dependency.
---    Delete from both the polymorphic table (the gate read) and the legacy one.
-DELETE FROM dependencies
- WHERE from_kind = 'task' AND from_id = 758 AND to_kind = 'task' AND to_id = 753;
-DELETE FROM task_dependencies
- WHERE task_id = 758 AND depends_on_task_id = 753;
-
--- 4. Move two misfiled game-art tasks to product V2 (they are world art, not
---    internal-track work): 586 grass_on_sand variety, 587 player_walk family.
-UPDATE tasks
-   SET version_id = 'V2', updated_at = now()
- WHERE id IN (586, 587)
-   AND version_id = 'GDS-V4';
-
--- 5. Carry every remaining NON-TERMINAL GDS-V4 task (the platform work) forward
---    to BONGOS-V1. Non-terminal = backlog/ready/completed/blocked. This leaves
---    the in-flight tail (10 confirmed + 1 active) and terminal history
---    (shipped/abandoned) attributed to GDS-V4, exactly like a normal
---    version-close carry-over. Runs AFTER steps 1/2/4 so the app / abandoned /
---    product tasks are already out of scope; self-correcting for the remainder.
-UPDATE tasks
-   SET version_id = 'BONGOS-V1', updated_at = now()
- WHERE version_id = 'GDS-V4'
-   AND status IN ('backlog', 'ready', 'completed', 'blocked');
-
--- 6. BONGOS-V1 becomes the single go-forward internal version: rename it off the
---    misleading "Bongos App" title (the app is now a GOAL inside it, step 1) and
---    mark it 'building' (it is actively being built).
-UPDATE versions
-   SET name = 'Cloud Bongos — platform (V1)', status = 'building'
- WHERE id = 'BONGOS-V1';
-
--- 7. Freeze GDS-V4 — sealed to new planning. Its 11 in-flight tasks land as its
---    final shipped history; its 358 shipped + 51 abandoned rows stay as the
---    archive of what GDS-V4 delivered. ('frozen', not 'shipped': GDS-V4 did not
---    ship — it was absorbed — and 'shipped' would falsely read 100% + could gate
---    the in-flight tail.)
-UPDATE versions
-   SET status = 'frozen'
- WHERE id = 'GDS-V4'
-   AND status <> 'shipped';
-
-COMMIT;

package/migrations/instance/183_gdsv4_carryover_themed_goals.sql

@@ -1,116 +0,0 @@
--- Migration 183 — Five themed goals for the GDS-V4 carryover (BONGOS-V1)
--- ============================================================================
--- Follow-up to ADR 0103 (migration 182): the ~72 still-relevant GDS-V4 tasks
--- carried into BONGOS-V1 were left goal-less. This gives the platform debt a
--- spine — five OUTCOME goals (ADR 0086 goal tier), each with done-when criteria,
--- and reparents the tasks under them. Evergreen chores + grader/economy/misc +
--- recent non-debt work are deliberately LEFT goal-less (they are not carryover
--- outcomes). Owner-directed 2026-07-02 (with Lars).
---
--- Goals are Archon-owned (created_by = 1), scope_modules empty (grouping goals,
--- not scope-walled; tasks attach here via this migration, not the API route).
--- Criteria start satisfied=false, so each goal stays 'open' until its work lands.
---
--- REVERSIBLE: only INSERTs (goals + criteria) and task goal_id UPDATEs. To undo,
--- NULL the goal_id on the affected tasks and DELETE the 5 goals + their criteria.
--- Idempotent: goal INSERTs are title-guarded, criteria use ON CONFLICT DO NOTHING,
--- task UPDATEs only touch still-goal-less rows.
--- ============================================================================
-
-BEGIN;
-
-DO $$
-DECLARE gid bigint;
-BEGIN
-  -- ---- G1: Build-pipeline integrity --------------------------------------
-  SELECT id INTO gid FROM goals WHERE version_id='BONGOS-V1' AND title='Build-pipeline integrity' LIMIT 1;
-  IF gid IS NULL THEN
-    INSERT INTO goals (version_id, title, description, scope_modules, created_by, status)
-    VALUES ('BONGOS-V1', 'Build-pipeline integrity',
-      'GDS-V4 carryover (ADR 0103): the system that builds Cloud Bongos never fails silently or carries known integrity holes — ship/merge/deploy, CI, the nightly backup, and the SEC-863 deploy-gate.',
-      '{}', 1, 'open')
-    RETURNING id INTO gid;
-  END IF;
-  INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order) VALUES
-    ('BONGOS-V1','gcarry-pipe-loud','Every stage of ship->merge->deploy and the nightly DB backup fails LOUDLY (surfaces in CI or journald), never silently.',gid,10),
-    ('BONGOS-V1','gcarry-pipe-sec863','The SEC-863 deploy-gate has no known bypass: audit range anchored to last-successful-deploy, sub-Metic protected-path claims blocked at claim time, and each protected-path commit tied to a task in the main audit.',gid,20),
-    ('BONGOS-V1','gcarry-pipe-smoke','A full-stack integration smoke (server + Postgres) runs as a required PR check, and the flaky unit harness is isolated so a green run is trustworthy.',gid,30)
-  ON CONFLICT (version_id, criterion_id) DO NOTHING;
-  UPDATE tasks SET goal_id=gid, updated_at=now()
-   WHERE version_id='BONGOS-V1' AND goal_id IS NULL
-     AND id IN (1426,1427,1429,1431,1432,1433,1435,1436,1462,1479,1641,1703,1219,861,862,1140,1437,1440,1461,1434,723);
-
-  -- ---- G2: Builder experience — hall, dev box, and skills ----------------
-  SELECT id INTO gid FROM goals WHERE version_id='BONGOS-V1' AND title='Builder experience — hall, dev box, and skills' LIMIT 1;
-  IF gid IS NULL THEN
-    INSERT INTO goals (version_id, title, description, scope_modules, created_by, status)
-    VALUES ('BONGOS-V1', 'Builder experience — hall, dev box, and skills',
-      'GDS-V4 carryover (ADR 0103): everything a builder directly touches — the builders hall UI, the dev box + sandbox, and the day-to-day skills — works without needing Claude for routine actions.',
-      '{}', 1, 'open')
-    RETURNING id INTO gid;
-  END IF;
-  INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order) VALUES
-    ('BONGOS-V1','gcarry-bx-hall','Core task actions (claim, release, ship-trigger, triage) and a task board work in the builders hall WITHOUT invoking the LLM.',gid,10),
-    ('BONGOS-V1','gcarry-bx-identity','A builder can view and edit their own profile, see works-completed, and read an efficiency-aware leaderboard.',gid,20),
-    ('BONGOS-V1','gcarry-bx-onramp','Newcomers never dead-end: auth/re-auth is browser-clickable and self-explanatory, and the dev box + sandbox are discoverable.',gid,30),
-    ('BONGOS-V1','gcarry-bx-box','A builder dev box + sandbox is robust: uncommitted work is not lost on reclaim, host-keys survive rebuilds, and staging is cross-platform.',gid,40)
-  ON CONFLICT (version_id, criterion_id) DO NOTHING;
-  UPDATE tasks SET goal_id=gid, updated_at=now()
-   WHERE version_id='BONGOS-V1' AND goal_id IS NULL
-     AND id IN (758,751,759,424,1466,1467,1468,1469,1471,1473,1474,1475,1476,1481,1482,594,1472,1715,1696,1650,1470,1391,1165,837,843,885,1477,1493,1430,1665);
-
-  -- ---- G3: Cloud Bongos productization and self-host ---------------------
-  SELECT id INTO gid FROM goals WHERE version_id='BONGOS-V1' AND title='Cloud Bongos productization and self-host' LIMIT 1;
-  IF gid IS NULL THEN
-    INSERT INTO goals (version_id, title, description, scope_modules, created_by, status)
-    VALUES ('BONGOS-V1', 'Cloud Bongos productization and self-host',
-      'GDS-V4 carryover (ADR 0103): someone other than the owner can run Cloud Bongos — a second instance, a real update channel, a clean vanilla boot, and hosting as a module.',
-      '{}', 1, 'open')
-    RETURNING id INTO gid;
-  END IF;
-  INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order) VALUES
-    ('BONGOS-V1','gcarry-prod-customer2','A second instance (Mercury) runs live on a pinned Cloud Bongos core, with its own repo and GDS.',gid,10),
-    ('BONGOS-V1','gcarry-prod-upgrade','bongos upgrade is a real update-consumption channel for a two-repo consumer (not a stub).',gid,20),
-    ('BONGOS-V1','gcarry-prod-vanilla','A vanilla docker compose up boots clean: no instance/product seed data runs and no host-brand leaks, both gated in CI.',gid,30),
-    ('BONGOS-V1','gcarry-prod-hosting','Instance hosting (provision, manage, cost read-out) is available as a Cloud Bongos module.',gid,40)
-  ON CONFLICT (version_id, criterion_id) DO NOTHING;
-  UPDATE tasks SET goal_id=gid, updated_at=now()
-   WHERE version_id='BONGOS-V1' AND goal_id IS NULL
-     AND id IN (1689,1690,1326,1704,1706,1485,1619,1620,1621,1388,1439);
-
-  -- ---- G4: Findability — the grep path (ADR 0095) ------------------------
-  SELECT id INTO gid FROM goals WHERE version_id='BONGOS-V1' AND title='Findability — the grep path (ADR 0095)' LIMIT 1;
-  IF gid IS NULL THEN
-    INSERT INTO goals (version_id, title, description, scope_modules, created_by, status)
-    VALUES ('BONGOS-V1', 'Findability — the grep path (ADR 0095)',
-      'GDS-V4 carryover (ADR 0103 / ADR 0095): a repo agents navigate by literal search, with meaning written into the source rather than an embedding index.',
-      '{}', 1, 'open')
-    RETURNING id INTO gid;
-  END IF;
-  INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order) VALUES
-    ('BONGOS-V1','gcarry-find-docstrings','The docstring / module-header convention is rolled out across the codebase and guarded by a fitness/density check so it cannot rot.',gid,10),
-    ('BONGOS-V1','gcarry-find-why','Code rationale (the why) is surfaced forward-facing, and the AST/tree-sitter repo-map upgrade is decided.',gid,20)
-  ON CONFLICT (version_id, criterion_id) DO NOTHING;
-  UPDATE tasks SET goal_id=gid, updated_at=now()
-   WHERE version_id='BONGOS-V1' AND goal_id IS NULL
-     AND id IN (1654,1655,1656,1657,1659,848);
-
-  -- ---- G5: Autonomy groundwork -------------------------------------------
-  SELECT id INTO gid FROM goals WHERE version_id='BONGOS-V1' AND title='Autonomy groundwork' LIMIT 1;
-  IF gid IS NULL THEN
-    INSERT INTO goals (version_id, title, description, scope_modules, created_by, status)
-    VALUES ('BONGOS-V1', 'Autonomy groundwork',
-      'GDS-V4 carryover (ADR 0103): safe unattended routines — guardrails first, then arm the safe set.',
-      '{}', 1, 'open')
-    RETURNING id INTO gid;
-  END IF;
-  INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order) VALUES
-    ('BONGOS-V1','gcarry-auto-guardrails','An off-droplet spend ceiling, a scoped file-only automation token, and a hall kill-switch all exist.',gid,10),
-    ('BONGOS-V1','gcarry-auto-armed','The cloud-routine execution environment is verified and the safe routine set is armed behind the autonomy flag.',gid,20)
-  ON CONFLICT (version_id, criterion_id) DO NOTHING;
-  UPDATE tasks SET goal_id=gid, updated_at=now()
-   WHERE version_id='BONGOS-V1' AND goal_id IS NULL
-     AND id IN (1393,1394,1395,1396);
-END $$;
-
-COMMIT;

package/migrations/instance/186_bongos_v1_governance_planning_seed.sql

@@ -1,69 +0,0 @@
--- 186_bongos_v1_governance_planning_seed.sql  (migrations/instance/ — OTB scope-truth)
--- Planning session (2026-07-03): the BONGOS-V1 "Governance — configurable roles &
--- permissions" goal + its six done-when criteria.
---
--- WHY THIS LIVES IN migrations/instance/ (ADR 0105 / selfhost-boot gate):
--- versions/goals/done_when_criteria are OTB scope-truth, NOT platform-universal
--- schema. In migrations/ root they would seed a vanilla third-party self-host with
--- OTB's governance criteria (the selfhost-boot VANILLA assertion: a fresh DB seeds
--- ZERO scope-truth). Here, migrate.sh applies the file only when the OWNING instance
--- opts in (GDS_APPLY_INSTANCE_SEEDS=1); a vanilla self-host skips the whole dir.
---
--- DR-SAFE: the goal was first created via the API (a runtime row), so a from-scratch
--- owning-instance replay would have no goal to parent the criteria under. This
--- migration recreates the goal idempotently (title-guard) so replay stays whole and
--- so it is a no-op on prod (where goal 30 already exists). Mirrors migration 183.
---
--- The 25 tasks (BV1.R90-R114) + dependency graph are seeded by
--- scripts/gds/seed-governance-tasks.js after this deploys (so the slugs resolve).
-
-BEGIN;
-
-DO $do$
-DECLARE gid bigint;
-BEGIN
-  SELECT id INTO gid FROM goals
-    WHERE version_id = 'BONGOS-V1'
-      AND title = 'Governance — configurable roles & permissions'
-    LIMIT 1;
-
-  IF gid IS NULL THEN
-    INSERT INTO goals (version_id, title, description, scope_modules, created_by, status)
-    VALUES (
-      'BONGOS-V1',
-      'Governance — configurable roles & permissions',
-      $desc$A core, Discord-style roles-and-permissions system where PERMISSIONS are the atomic primitive and ranks become seeded roles. Adds first-class principals (machine identities), session-scopes (box tokens), ownership-scoped permissions, and a governance-owned protected-surface registry (policy owns / substrate enforces). Capability lives in core (modules/governance/, default:true); per-project settings split config/governance.json (over neutral) + governance_* DB tables. Ships an Archon-only Governance hall tab (assign + toggle; system permissions locked). Preserves the ADR 0016 trust boundary end-to-end. Protected-scope (kernel/lifecycle) -> Archon-mediated.$desc$,
-      '{kernel,lifecycle,hall-ui}',
-      1,
-      'open'
-    )
-    RETURNING id INTO gid;
-  END IF;
-
-  INSERT INTO done_when_criteria (version_id, criterion_id, criterion_md, goal_id, sort_order) VALUES
-  ('BONGOS-V1', 'gov-perms-atom',
-   $md$**Permissions become the atom; ranks become seeded roles — with zero day-one behavior change.** Authority stops being a fixed rank threshold and becomes a resolved set of granular permissions. Done when: a code-defined permission catalog exists (each permission flagged `system` or not, since permissions map to real routes and cannot be UI-invented); a per-request, uncached resolver returns a builder's effective permission set as the union of their roles (preserving ADR 0016); four seeded roles (`xenos`/`thetes`/`metic`/`archon`) reproduce today's thresholds exactly; a `requirePermission()` gate exists alongside `requireRank`; and a parity test proves every builder resolves to exactly today's powers (behavior-identical at ship).$md$,
-   gid, 20),
-  ('BONGOS-V1', 'gov-gates-permissioned',
-   $md$**Every DB-resolvable authority gate reads permissions, not rank.** Rank stops being special everywhere the server decides access. Done when: the ~60 HTTP route gates migrate `requireRank(...)` -> `requirePermission(...)`; claim eligibility (`xenosClaimAllowed`/`rankAllowsTask`/per-task floor), the page-level gates, and the wandering-prefs clamp are re-expressed as permissions; the ~6 duplicated numeric rank-tier maps collapse into the single resolver; and the `route-rank-check` fitness function is updated to assert permission gates so nothing silently regresses.$md$,
-   gid, 21),
-  ('BONGOS-V1', 'gov-full-model',
-   $md$**The complete authority model is represented — not just role -> permission.** The 2026-07-03 authority sweep proved Cloud Bongos authority runs on ~7 mechanisms, not one. Done when: first-class **principals** (machine identities like the BFG memory-writer and the Discord bot, keyed on `system_role`, never UI-grantable) are modeled; **session-scopes** (box-scoped tokens, deny-by-default) are a first-class capability distinct from a builder's roles; **ownership-scoped** permissions ("act on *own* X" — own box/memory/credentials/claim) are expressible; and the **protected-surface registry** (today's `PROTECTED_GLOBS` / `EXPECTED_RANKS`) becomes governance-owned *data* while the out-of-band substrate (git hooks, CI, GitHub branch protection, SSH) stays the *enforcer* — policy owns, substrate enforces.$md$,
-   gid, 22),
-  ('BONGOS-V1', 'gov-core-project-split',
-   $md$**Capability lives in core; settings live per project.** The governance engine is portable to any Cloud Bongos instance; each project keeps its own governance data. Done when: `modules/governance/` is a `default:true` core module with its own `governance_*` additive migrations and a resolver exposed through a kernel port; role *templates/defaults* ship as `config/governance.json` resolved over a `config/governance.neutral.json` (the branding pattern); live role/permission/assignment *data* lives in the DB; and a fresh vanilla instance boots with sane neutral defaults and no OTB identity.$md$,
-   gid, 23),
-  ('BONGOS-V1', 'gov-archon-tab',
-   $md$**The Archon Governance tab — assign + toggle.** The owner can configure governance from the builders' hall, Discord-style. Done when: an Archon-only Governance tab lets you view/edit the ~12 operational permissions per role, create custom roles, and assign roles to builders; `system` permissions render **locked** (visible but not grantable); and the tab is gated in depth at the page layer (`serve-internal`), the API layer (`governance.manage`), and pinned in `route-rank-check`.$md$,
-   gid, 24),
-  ('BONGOS-V1', 'gov-boundary-proof',
-   $md$**The trust boundary provably holds — with a live proof and the docs corrected.** This criterion de-risks the whole goal: no amount of governance configuration can weaken production safety. Done when: an abuse-matrix test proves no configurable role/permission can grant a low-trust builder deploy or protected-path access; a live demonstration creates a custom role granting an operational permission (it works) while a `system` permission stays enforced by substrate; an ADR records the "permissions-as-atom + principals + session-scopes + protected-surface registry, policy-owns/substrate-enforces" decision; and the stale ADR 0043 / canonical-permissions.md branch-protection claims are fixed (GitHub branch protection is now live).$md$,
-   gid, 25)
-  ON CONFLICT (version_id, criterion_id) DO UPDATE
-    SET criterion_md = EXCLUDED.criterion_md,
-        goal_id      = EXCLUDED.goal_id,
-        sort_order   = EXCLUDED.sort_order;
-END
-$do$;
-
-COMMIT;

package/scripts/gds/art-stage.js

@@ -1,152 +0,0 @@
-#!/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);
-  });
-}