@bongos/core 1.21.175 → 1.21.176

package/scripts/gds/runner-drift.js

@@ -1,151 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/runner-drift.js — do the intent-runner units run the core this instance installed? (task 1002722)
-//
-// WHY. For weeks the prod intent runners ran core 1.19.2 from a retired clone while the
-// instance served a current core, so an owner's domain-attach click executed as a TEARDOWN
-// (task 1002716). The hotfix repointed the units with systemd drop-ins; nothing noticed the
-// drift, and the only tell was a PWD in sudo logs. This reads each `*intent-runner*` unit the
-// way systemd does (a drop-in overrides the base file), finds the core package the ExecStart
-// script lives in, and compares its version to the instance's installed @bongos/core.
-//
-// A unit whose version cannot be read — a shell wrapper that picks the core at runtime, a
-// missing package — is UNRESOLVED, never ok: a gate that guesses green is the incident again.
-//
-//   node scripts/gds/runner-drift.js [--instance-root <dir>] [--json]
-//     exit 0 = every unit resolved and matched (or no systemd here), 1 = drift, 2 = bad usage.
-//     Unresolved units are listed but do not fail the run. `bongos doctor` runs the same check.
+// scripts/gds/runner-drift.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/runner-drift.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
 'use strict';
-
-const fs = require('node:fs');
-const path = require('node:path');
-const { spawnSync } = require('node:child_process');
-
-const CORE_NAMES = ['@bongos/core', '@cloudbongos/core'];
-const P = path.posix;   // unit files describe the Linux control plane, whatever runs the tests
-
-// The effective WorkingDirectory + ExecStart lines from `systemctl cat` output. Later files
-// are drop-ins: a later WorkingDirectory wins, an empty `ExecStart=` clears the list, and a
-// drop-in that only ADDS one leaves the base command running too (oneshot runs them all).
-function effectiveUnit(catText) {
-  let workingDirectory = null;
-  let execs = [];
-  for (const raw of String(catText || '').split(/\r?\n/)) {
-    const line = raw.trim();
-    const m = line.match(/^(WorkingDirectory|ExecStart)=(.*)$/);
-    if (!m) continue;
-    const value = m[2].trim();
-    if (m[1] === 'WorkingDirectory') workingDirectory = value.replace(/^-/, '') || null;
-    else if (value === '') execs = [];
-    else execs.push(value);
-  }
-  return { workingDirectory, execStarts: execs };
-}
-
-// The absolute path of the .js script an ExecStart runs, or null when its first argument is
-// not one (a shell wrapper decides at runtime which core it loads).
-function runnerScriptPath({ workingDirectory, execStart }) {
-  const tokens = String(execStart || '').trim().split(/\s+/).filter(Boolean);
-  if (!tokens.length) return null;
-  let i = 0;
-  if (P.basename(tokens[i].replace(/^[@\-:+!]+/, '')) === 'env') {
-    i++;
-    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
-  }
-  const script = tokens.slice(i + 1).find((tok) => !tok.startsWith('-'));
-  if (!script || !/\.[cm]?js$/.test(script)) return null;
-  if (script.startsWith('/')) return script;
-  return workingDirectory ? P.join(workingDirectory, script) : null;
-}
-
-function readJson(p, fsImpl) {
-  try { return JSON.parse(fsImpl.readFileSync(p, 'utf8')); } catch { return null; }
-}
-
-// The core version a script belongs to: the nearest enclosing @bongos/core package, or a
-// source checkout's CORE_VERSION. Null when neither is found.
-function coreVersionFor(scriptPath, { fsImpl = fs } = {}) {
-  let dir = P.dirname(String(scriptPath || ''));
-  for (;;) {
-    const pkg = readJson(P.join(dir, 'package.json'), fsImpl);
-    if (pkg && CORE_NAMES.includes(pkg.name) && pkg.version) return String(pkg.version);
-    try {
-      const m = String(fsImpl.readFileSync(P.join(dir, 'src', 'module-api.js'), 'utf8')).match(/CORE_VERSION\s*=\s*['"]([^'"]+)['"]/);
-      if (m) return m[1];
-    } catch { /* not a checkout root */ }
-    const up = P.dirname(dir);
-    if (up === dir) return null;
-    dir = up;
-  }
-}
-
-function installedCoreVersion(instanceRoot, { fsImpl = fs } = {}) {
-  if (!instanceRoot) return null;
-  for (const name of CORE_NAMES) {
-    const pkg = readJson(P.join(instanceRoot, 'node_modules', name, 'package.json'), fsImpl);
-    if (pkg && pkg.version) return String(pkg.version);
-  }
-  return null;
-}
-
-function assessExecStart({ workingDirectory, execStart, instanceVersion, instanceRoot, fsImpl }) {
-  const scriptPath = runnerScriptPath({ workingDirectory, execStart });
-  const base = { scriptPath, runnerVersion: null, instanceVersion };
-  if (!scriptPath) return { ...base, status: 'unresolved', reason: `ExecStart does not run a .js script directly (${execStart}) — cannot tell which core it loads` };
-  const runnerVersion = coreVersionFor(scriptPath, { fsImpl });
-  const found = { ...base, runnerVersion };
-  if (!runnerVersion) return { ...found, status: 'unresolved', reason: `no core version found above ${scriptPath}` };
-  if (!instanceVersion) return { ...found, status: 'unresolved', reason: `no installed @bongos/core under ${instanceRoot}` };
-  if (runnerVersion === instanceVersion) return { ...found, status: 'ok', reason: `runs core ${runnerVersion}` };
-  return { ...found, status: 'drift', reason: `runs core ${runnerVersion} (${scriptPath}) but the instance installed ${instanceVersion} at ${instanceRoot}` };
-}
-
-// One verdict per unit, from its WORST ExecStart: drift, then unresolved, then ok.
-function assessRunnerUnit({ name, catText, instanceRoot, fsImpl = fs }) {
-  const { workingDirectory, execStarts } = effectiveUnit(catText);
-  const instanceVersion = installedCoreVersion(instanceRoot, { fsImpl });
-  if (!execStarts.length) return { name, status: 'unresolved', reason: 'no ExecStart in the unit', scriptPath: null, runnerVersion: null, instanceVersion };
-  const all = execStarts.map((execStart) => assessExecStart({ workingDirectory, execStart, instanceVersion, instanceRoot, fsImpl }));
-  const worst = ['drift', 'unresolved', 'ok'].map((s) => all.find((r) => r.status === s)).find(Boolean);
-  return { name, ...worst };
-}
-
-function parseUnitList(stdout) {
-  return String(stdout || '').split(/\r?\n/).map((l) => l.trim().split(/\s+/)[0]).filter((n) => n && n.endsWith('.service'));
-}
-
-// The first line of every run-intents, so a journal grep shows a stale runner at once.
-function runnerBanner({ runnerVersion, runnerRoot, instanceVersion, instanceRoot }) {
-  const tail = instanceVersion ? `instance core ${instanceVersion} at ${instanceRoot}` : `no installed core at ${instanceRoot}`;
-  const line = `runner core ${runnerVersion || '?'} from ${runnerRoot} (${tail})`;
-  return runnerVersion && instanceVersion && runnerVersion !== instanceVersion ? `⚠ DRIFT: ${line}` : line;
-}
-
-// Every intent-runner unit on this host, assessed. Null when there is no systemd to ask.
-function collectRunnerDrift({ instanceRoot }) {
-  const run = (args) => spawnSync('systemctl', args, { encoding: 'utf8', timeout: 15000 });
-  const list = run(['list-units', '--all', '--plain', '--no-legend', '--no-pager', '--type=service', '*intent-runner*']);
-  if (list.error || list.status !== 0) return null;
-  return parseUnitList(list.stdout).map((name) => {
-    const cat = run(['cat', '--no-pager', name]);
-    return assessRunnerUnit({ name, catText: cat.status === 0 ? cat.stdout : '', instanceRoot });
-  });
-}
-
-function main(argv) {
-  const at = argv.indexOf('--instance-root');
-  const instanceRoot = (at >= 0 ? argv[at + 1] : null) || process.env.BONGOS_INSTANCE_ROOT;
-  if (!instanceRoot) {
-    console.error('runner-drift: name the instance root — --instance-root <dir> or BONGOS_INSTANCE_ROOT');
-    return 2;
-  }
-  const results = collectRunnerDrift({ instanceRoot });
-  if (argv.includes('--json')) console.log(JSON.stringify({ instanceRoot, systemd: results !== null, units: results || [] }, null, 2));
-  else if (results === null) console.log('runner-drift: no systemd on this host — nothing to check');
-  else if (!results.length) console.log('runner-drift: no *intent-runner* units on this host');
-  else for (const r of results) console.log(`${r.status === 'ok' ? '✓' : r.status === 'drift' ? '✖' : '?'} ${r.name}: ${r.reason}`);
-  return results && results.some((r) => r.status === 'drift') ? 1 : 0;
-}
-
-module.exports = { effectiveUnit, runnerScriptPath, coreVersionFor, installedCoreVersion, assessRunnerUnit, parseUnitList, runnerBanner, collectRunnerDrift };
-
-if (require.main === module) process.exitCode = main(process.argv.slice(2));
+require('../bongos/forwarder.js').forward(module, 'runner-drift.js');

package/scripts/gds/sandbox-stage.js

@@ -1,459 +1,7 @@
 #!/usr/bin/env node
-// scripts/gds/sandbox-stage.js — stage the current working tree on the
-// builder's own live game preview (the "sandbox", ADR 0044) so a change can be
-// REVIEWED in a browser before /builder-ship pushes it toward the main game.
-// (#927, ADR 0046 — the sandbox-first review step.)
-//
-// The preview is LOCAL (task 1056): a builder on a full clone runs the ADR 0052
-// game-only entry privately at http://localhost:<port> via
-// scripts/gds/local-preview.js, and "staging" (re)starts that process to pick up
-// the current working tree, health-checks it, records a marker of exactly WHAT
-// tree state was staged, and hands back the URL. ship.js consults the marker
-// through runShipGate(): if the tree changed since the last staging, the builder
-// is asked to stage + review again before the claim resolves. On approval (a TTY
-// 'y' or an --approved re-run on a fresh stage) the gate returns a durable
-// self-approval record that ship.js persists on the task (#1048).
-//
-// Usage (a checkout with no game has no sandbox; the script says so):
-//   node scripts/gds/sandbox-stage.js            # stage + print the review URL
-//   node scripts/gds/sandbox-stage.js status     # preview state + is the marker current?
-//   node scripts/gds/sandbox-stage.js url        # just print the sandbox URL
-
-const { execFileSync } = require('node:child_process');
-const crypto = require('node:crypto');
-const fs = require('node:fs');
-const os = require('node:os');
-const path = require('node:path');
-const readline = require('node:readline');
-const localPreview = require('./local-preview-lib');
-
-// The default health URL waitHealthy probes when a caller supplies none; the
-// local context always passes its own (localPreview.healthUrl).
-const HEALTH_URL = 'http://127.0.0.1:3000/';
-const HEALTH_TIMEOUT_MS = 90_000; // a cold first start can be slow
-const HEALTH_POLL_MS = 2_000;
-
-// Game surfaces the sandbox can actually show. The sandbox host serves the
-// GAME-ONLY entry (src/preview-server.js, ADR 0052), so only game-rendering paths
-// are previewable — GDS/internal-tooling diffs have nothing to look at there.
-// src/preview-server.js + server.js are the entrypoints that render the game.
-// The GAME CLIENT directories the sandbox renders. These MOVED in the module
-// carve (ADR 0083, BV1.R49 / task 1418): public/ -> modules/game/public/,
-// src/world/ -> modules/game/world/, src/rooms/ -> modules/game/rooms/. The
-// pre-carve spelling sat here matching NOTHING for 69 days (task 1002062), so
-// tests/sandbox_stage.mjs pins the list against the real tree.
-const PREVIEWABLE_DIRS = ['modules/game/public', 'modules/game/world', 'modules/game/rooms'];
-// The entrypoints that render the game.
-const PREVIEWABLE_ENTRYPOINTS = ['server.js', 'src/preview-server.js'];
-// DERIVED, all three of them. They used to be three hand-maintained copies of the
-// same list, and the carve updated none of them; deriving removes the drift class
-// rather than just this instance of it.
-const PREVIEWABLE_PREFIXES = PREVIEWABLE_DIRS.map((d) => `${d}/`);
-const PREVIEWABLE_FILES = new Set(PREVIEWABLE_ENTRYPOINTS);
-const PREVIEWABLE_PATHSPECS = [...PREVIEWABLE_DIRS, ...PREVIEWABLE_ENTRYPOINTS];
-
-function isPreviewableFile(file) {
-  const fp = String(file || '').replace(/\\/g, '/');
-  if (PREVIEWABLE_FILES.has(fp)) return true;
-  return PREVIEWABLE_PREFIXES.some((p) => fp.startsWith(p));
-}
-
-function anyPreviewable(files) {
-  return (files || []).some(isPreviewableFile);
-}
-
-// Identity of the staged state: a CONTENT hash of the previewable game
-// surfaces as they sit in the working tree right now — exactly what the
-// sandbox serves. Scoped + content-stable on purpose:
-//   - editing docs/GDS files does NOT invalidate a staged review (the sandbox
-//     shows none of that), and
-//   - `git add` / committing the SAME content does not either (blob hashes are
-//     content hashes), so the natural stage → review → commit → ship flow
-//     keeps the marker fresh.
-// Any actual change to a game file (tracked, staged, or untracked) produces a
-// different stamp and the ship gate asks for a fresh stage + review. Returns
-// null if git fails (not a repo) — callers treat that as "cannot assert
-// freshness".
-function computeTreeStamp(deps = {}) {
-  const run = deps.execFileSync || execFileSync;
-  const cwd = deps.cwd || process.cwd();
-  try {
-    const tracked = run('git', ['ls-files', '--', ...PREVIEWABLE_PATHSPECS], { cwd, encoding: 'utf8' });
-    const untracked = run('git', ['ls-files', '-o', '--exclude-standard', '--', ...PREVIEWABLE_PATHSPECS], { cwd, encoding: 'utf8' });
-    const f = deps.fs || fs;
-    const files = [...new Set([...tracked.split('\n'), ...untracked.split('\n')])]
-      .filter(Boolean)
-      .filter((p) => f.existsSync(path.join(cwd, p))) // deleted-but-still-indexed files
-      .sort();
-    const hashes = files.length === 0 ? '' : run('git', ['hash-object', '--stdin-paths'], {
-      cwd, encoding: 'utf8', input: files.join('\n') + '\n', maxBuffer: 64 * 1024 * 1024,
-    });
-    // The sorted file list is part of the stamp so deletions/renames count too.
-    return crypto.createHash('sha256').update(files.join('\n') + '\n' + hashes).digest('hex');
-  } catch {
-    return null;
-  }
-}
-
-// True when the WORKING TREE has uncommitted (or untracked) changes on a
-// previewable surface — the committed diff alone misses these, but the
-// sandbox shows them, so the gate must too.
-function workingTreePreviewable(deps = {}) {
-  const run = deps.execFileSync || execFileSync;
-  const cwd = deps.cwd || process.cwd();
-  try {
-    const out = run('git', ['status', '--porcelain', '--', ...PREVIEWABLE_PATHSPECS], { cwd, encoding: 'utf8' });
-    return out.trim().length > 0;
-  } catch {
-    return false;
-  }
-}
-
-function markerPath(deps = {}) {
-  return deps.markerPath || path.join((deps.tmpdir || os.tmpdir)(), 'otb-sandbox-staged.json');
-}
-
-function readMarker(deps = {}) {
-  const f = deps.fs || fs;
-  try {
-    return JSON.parse(f.readFileSync(markerPath(deps), 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-function writeMarker(marker, deps = {}) {
-  const f = deps.fs || fs;
-  f.writeFileSync(markerPath(deps), JSON.stringify(marker, null, 2) + '\n');
-}
-
-// Pure decision for the ship gate. Returns one of:
-//   skip        — gate doesn't apply (no sandbox here / nothing previewable / no
-//                 preview URL / --skip-stage); ship proceeds untouched.
-//   pass        — current game-surface state is already staged on the sandbox;
-//                 the builder had their review opportunity — proceed.
-//   review      — interactive TTY: stage now, hand over the URL, ask before
-//                 resolving.
-//   stage_abort — non-interactive (the dominant case: an agent-driven session
-//                 runs ship.js through a non-TTY shell): stage so the sandbox
-//                 shows the work, then ABORT with the claim intact and the
-//                 review URL. The agent relays the URL, the human reviews, and
-//                 the re-run passes on the now-fresh marker. Never hangs on
-//                 stdin; never silently skips the review.
-// gateActive = there IS a sandbox here to review on (a local game preview).
-function decideShipGate({ gateActive, previewUrl: url, previewable, stagedFresh, tty, skipStage }) {
-  if (skipStage) return { action: 'skip', reason: '--skip-stage' };
-  if (!gateActive) return { action: 'skip', reason: 'no sandbox here (no local game preview)' };
-  if (!previewable) return { action: 'skip', reason: 'no previewable game surfaces in the diff' };
-  if (!url) return { action: 'skip', reason: 'preview has no URL (local preview unavailable)' };
-  if (stagedFresh) return { action: 'pass', reason: 'working tree already staged' };
-  return tty ? { action: 'review', reason: 'stage + review before ship' }
-             : { action: 'stage_abort', reason: 'non-interactive: stage, then pause for review' };
-}
-
-// task 1002607: the discriminator probe URL — same origin as the health URL, at
-// the API healthz path only the FULL server mounts. Pure + exported for tests.
-function apiHealthzProbeUrl(healthUrl) {
-  try { return new URL('/api/bongos/healthz', healthUrl).toString(); } catch { return null; }
-}
-
-// task 1002607: is the thing answering the health URL actually the MAIN server?
-// The game-only preview entry (ADR 0052) mounts no /api/bongos, so a 200 from the
-// API healthz proves the answerer is the full server — which can hold the very
-// port the preview was asked to bind — not the preview. A probe error/404 means
-// "not the main server", which is the expected preview answer.
-async function answeredByMainServer(healthUrl, fetchImpl) {
-  const probe = apiHealthzProbeUrl(healthUrl);
-  if (!probe) return false;
-  try {
-    const res = await fetchImpl(probe, { signal: AbortSignal.timeout(5_000) });
-    return res.status === 200;
-  } catch {
-    return false;
-  }
-}
-
-async function waitHealthy(deps = {}) {
-  const fetchImpl = deps.fetchImpl || fetch;
-  const healthUrl = deps.healthUrl || HEALTH_URL;
-  const deadline = Date.now() + (deps.timeoutMs || HEALTH_TIMEOUT_MS);
-  let lastErr = 'no response';
-  while (Date.now() < deadline) {
-    try {
-      const res = await fetchImpl(healthUrl, { signal: AbortSignal.timeout(5_000) });
-      // task 1002607: was `< 500`, which called a 404 "healthy" — any wrong server
-      // with nothing at '/' passed. And a good status alone doesn't prove the
-      // PREVIEW answered: the main server binds the same port, so a dead preview
-      // "passed" whenever the full server was up. Cross-examine the answerer.
-      if (res.status < 400) {
-        if (await answeredByMainServer(healthUrl, fetchImpl)) {
-          return {
-            ok: false,
-            reason: `${healthUrl} is answered by the MAIN server (/api/bongos/healthz responded 200), not the game preview — the preview did not start (its port is taken by the full server)`,
-          };
-        }
-        return { ok: true };
-      }
-      lastErr = `HTTP ${res.status}`;
-    } catch (e) {
-      lastErr = e.message;
-    }
-    await new Promise((r) => setTimeout(r, deps.pollMs || HEALTH_POLL_MS));
-  }
-  return { ok: false, reason: lastErr };
-}
-
-// Which sandbox does this machine have? A full LOCAL clone (task 1056) is keyed by
-// the presence of the game-only entry (src/preview-server.js). Returns a uniform
-// context { kind, url, healthUrl, restart(deps) } — or null when there is NO
-// sandbox here (a checkout with no game). deps.previewContext short-circuits for
-// hermetic tests.
-function resolvePreviewContext(deps = {}) {
-  if (deps.previewContext !== undefined) return deps.previewContext;
-  if (localPreview.hasGameEntry(deps)) {
-    return {
-      kind: 'local',
-      url: localPreview.localUrl(deps),
-      healthUrl: localPreview.healthUrl(deps),
-      // localPreview.restart returns {ok,reason}; throw so stage()'s try/catch
-      // turns a failed local start into the standard "could not start" reason.
-      restart: (d) => { const r = localPreview.restart(d); if (!r.ok) throw new Error(r.reason); },
-    };
-  }
-  return null;
-}
-
-// Stage the current working tree: (re)start the resolved preview, wait for it to
-// answer, write the staged marker. Returns { ok, url, kind, reason? }.
-async function stage({ taskId } = {}, deps = {}) {
-  const ctx = resolvePreviewContext(deps);
-  if (!ctx) return { ok: false, reason: 'no sandbox here (this checkout has no local game preview)' };
-  if (!ctx.url) return { ok: false, reason: 'local preview URL unavailable' };
-  console.log('Staging your working tree on your local sandbox (starting the game preview)...');
-  try {
-    ctx.restart(deps);
-  } catch (e) {
-    return { ok: false, reason: `could not start the ${ctx.kind} preview: ${e.message}` };
-  }
-  const health = await waitHealthy({ ...deps, healthUrl: ctx.healthUrl });
-  if (!health.ok) {
-    return { ok: false, reason: `preview did not come up healthy (${health.reason}) — check 'node scripts/gds/local-preview.js logs'` };
-  }
-  writeMarker({
-    stamp: computeTreeStamp(deps),
-    url: ctx.url,
-    kind: ctx.kind,
-    task_id: taskId ?? null,
-    staged_at: new Date().toISOString(),
-  }, deps);
-  return { ok: true, url: ctx.url, kind: ctx.kind };
-}
-
-function promptYesNo(question) {
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(/^y(es)?$/i.test(String(answer || '').trim()));
-    });
-  });
-}
-
-// The prominent, easy-to-surface review block (#1048). ship.js almost always
-// runs in a NON-TTY shell inside the builder's Claude session, so the AGENT is
-// the one that relays this to the human — the /builder-ship skill instructs it
-// to present the URL as its own callout in chat. Keep the URL ALONE on its own
-// line, framed by a rule, so it stands out from the surrounding log noise and
-// stays clickable. This is the moment the change is "ready to review", so the
-// link has to be impossible to miss. The URL (http://localhost:<port>) is
-// passed in.
-function printReviewBlock(url, taskId) {
-  const bar = '─'.repeat(64);
-  console.log('');
-  console.log(bar);
-  console.log('  🔍 REVIEW REQUIRED — your change is live on YOUR sandbox (not prod)');
-  console.log('');
-  console.log(`      ${url}`);
-  console.log('');
-  console.log(`  Open that link and walk through the change in the browser${taskId ? ` (task #${taskId})` : ''}.`);
-  console.log('  When it looks right, approve to ship to the main game:');
-  console.log('      re-run /builder-ship --approved   ← records your sign-off');
-  console.log(bar);
-  console.log('');
-}
-
-// Build the recorded-approval payload ship.js threads into the resolve call
-// (#1048). The server stamps `by`/`at` authoritatively — we only supply the
-// content stamp of what was reviewed, the sandbox URL, and HOW it was approved.
-function approvalRecord(method, url, deps) {
-  return { stamp: computeTreeStamp(deps), url, method };
-}
-
-// The gate ship.js runs before resolving the claim (#927, ADR 0046).
-// Returns { ok: true } to proceed or { ok: false, reason } to abort the ship
-// with the claim still active so the builder can iterate. On a recorded
-// approval it also returns { sandboxReview } so ship.js can persist the
-// self-approval as a durable fact on the task (#1048).
-//
-// `approved` (the --approved flag) records the builder's sign-off, but ONLY
-// when the current game state is already staged-fresh (decideShipGate → 'pass')
-// — i.e. a re-run after the work was staged and reviewed on a prior invocation.
-// It can never short-circuit the first stage+review of a change: a stale/absent
-// marker still stages and pauses, so there is nothing to "pre-approve".
-async function runShipGate({ taskId, files, skipStage, tty, approved }, deps = {}) {
-  const ctx = resolvePreviewContext(deps);
-  const gateActive = Boolean(ctx);
-  const url = ctx ? ctx.url : null;
-  // Previewable = the committed diff OR uncommitted working-tree edits touch a
-  // game surface — the sandbox serves the working tree, so both views count.
-  const previewable = anyPreviewable(files) || (gateActive && workingTreePreviewable(deps));
-  const marker = gateActive ? readMarker(deps) : null;
-  const stamp = gateActive ? computeTreeStamp(deps) : null;
-  const stagedFresh = Boolean(stamp && marker && marker.stamp === stamp);
-  const d = decideShipGate({ gateActive, previewUrl: url, previewable, stagedFresh, tty, skipStage });
-
-  if (d.action === 'skip') {
-    if (gateActive && previewable) console.log(`Sandbox review gate: skipped (${d.reason}).`);
-    return { ok: true };
-  }
-  if (d.action === 'pass') {
-    // This exact game state is already staged + reviewable on the sandbox.
-    if (approved) {
-      // Explicit sign-off after an out-of-band review — record it (#1048).
-      console.log(`Sandbox review: recorded your approval of ${url} — shipping to the main game.`);
-      return { ok: true, sandboxReview: approvalRecord('flag', url, deps) };
-    }
-    // Back-compat / failure-open: a bare fresh-marker re-run still ships, but
-    // there is no human sign-off to record. Nudge toward --approved next time.
-    console.log(`Sandbox review: this exact game state is already staged at ${url} — proceeding.`);
-    console.log('  note: no sandbox approval recorded (re-ran on a fresh stage without --approved);');
-    console.log('  re-run /builder-ship --approved after reviewing to record your sign-off.');
-    return { ok: true };
-  }
-
-  // 'review' and 'stage_abort' both stage first so the sandbox shows the work.
-  // Reuse the already-resolved context so we don't resolve it twice.
-  const staged = await stage({ taskId }, { ...deps, previewContext: ctx });
-  if (!staged.ok) {
-    // task 1002607 (§4.4 station 9): a staging failure (the preview didn't come up)
-    // used to WARN one stderr line and return ok — the review gate silently
-    // turned itself off and the ship went on as if the review had happened.
-    // Fail closed like the smoke gate (task 1002605): abort with the claim
-    // intact; --skip-stage is the explicit, visible bypass. No review:true —
-    // this is a failure to present, not a calm review pause.
-    return {
-      ok: false,
-      reason: `sandbox staging failed (${staged.reason}) — the sandbox review step DID NOT run. Fix the preview and re-run /builder-ship, or run /builder-ship --skip-stage to explicitly ship WITHOUT the sandbox review. Your claim is still active`,
-    };
-  }
-
-  if (d.action === 'stage_abort') {
-    printReviewBlock(staged.url, taskId);
-    return {
-      ok: false,
-      review: true,
-      url: staged.url,
-      reason: `game changes must be reviewed on the sandbox before shipping — staged at ${staged.url}; open it, review the change (suggest fixes if needed), then re-run /builder-ship --approved to record your sign-off and ship (--skip-stage to bypass)`,
-    };
-  }
-
-  // Interactive (TTY): show the same prominent block, then ask in-line.
-  printReviewBlock(staged.url, taskId);
-  const yes = await (deps.promptYesNo || promptYesNo)(
-    'Reviewed on the sandbox — ship this to the main game? [y/N]: '
-  );
-  if (!yes) {
-    return {
-      ok: false,
-      review: true,
-      url: staged.url,
-      reason: `sandbox review declined — iterate on the change, restage (node scripts/gds/sandbox-stage.js), and re-run /builder-ship when it looks right at ${staged.url}`,
-    };
-  }
-  // A TTY 'y' IS the explicit approval — record it (#1048).
-  return { ok: true, sandboxReview: approvalRecord('tty', staged.url, deps) };
-}
-
-// task 1002607: the old message ("this clone has no game preview entry") implied
-// the BUILDER's clone was at fault, when the commonest cause is that the checkout
-// simply carries no game — src/preview-server.js is an instance's product file
-// (the ADR 0052 game-only server); the core repo does not ship one. Name what is
-// actually missing and both real causes. Exported so the wording is pinned.
-const NO_SANDBOX_MSG =
-  'No sandbox here: this checkout has no game preview entry (src/preview-server.js — the ADR 0052 game-only server).';
-const NO_SANDBOX_DETAIL =
-  'That entry file comes from an instance\'s product layer. This repo does not ship one, and a partial/sparse clone of an instance that has one also lacks it — nothing here can be staged or previewed.';
-
-async function cliMain() {
-  const cmd = process.argv[2] || 'stage';
-  const ctx = resolvePreviewContext();
-  const NO_SANDBOX = NO_SANDBOX_MSG;
-
-  if (cmd === 'url') {
-    console.log(ctx && ctx.url ? ctx.url : '(no sandbox here — no local game preview in this checkout)');
-    return;
-  }
-  if (cmd === 'status') {
-    if (!ctx) { console.log(NO_SANDBOX); return; }
-    const marker = readMarker();
-    const stamp = computeTreeStamp();
-    const fresh = Boolean(stamp && marker && marker.stamp === stamp);
-    console.log(`sandbox kind:   ${ctx.kind}`);
-    console.log(`sandbox URL:    ${ctx.url || '(none)'}`);
-    if (ctx.kind === 'local') {
-      console.log(`local preview:  ${localPreview.isRunning() ? `running (pid ${localPreview.readPid()})` : 'stopped — staging will start it'}`);
-    }
-    console.log(`staged marker:  ${marker ? `staged ${marker.staged_at}${marker.task_id ? ` (task #${marker.task_id})` : ''}` : '(never staged)'}`);
-    console.log(`current game state: ${fresh ? 'MATCHES the staged state — sandbox is current' : 'differs from the staged state — run sandbox-stage to refresh'}`);
-    return;
-  }
-  if (cmd !== 'stage') {
-    console.error(`sandbox-stage: unknown command '${cmd}' (try: stage | status | url)`);
-    process.exit(2);
-  }
-  if (!ctx) {
-    // task 1002607: an explicit `stage` invocation that can stage nothing is a
-    // FAILED command, not a quiet success — exit 1 was exit 0, which read as
-    // "staged fine" to any caller that only checks the code.
-    console.log(NO_SANDBOX);
-    console.log(NO_SANDBOX_DETAIL);
-    process.exit(1);
-  }
-  const res = await stage({});
-  if (!res.ok) {
-    console.error(`sandbox-stage failed: ${res.reason}`);
-    process.exit(1);
-  }
-  console.log('');
-  console.log(`Staged. Review your change in a browser at: ${res.url}`);
-  if (res.kind === 'local') console.log('(A private localhost copy — degraded DB, nothing shipped. Edit + re-run to refresh.)');
-  console.log('When it looks right, run /builder-ship to push it to the main game.');
-}
-
-module.exports = {
-  isPreviewableFile,
-  anyPreviewable,
-  computeTreeStamp,
-  workingTreePreviewable,
-  markerPath,
-  readMarker,
-  writeMarker,
-  decideShipGate,
-  resolvePreviewContext,
-  stage,
-  runShipGate,
-  PREVIEWABLE_PATHSPECS,
-  PREVIEWABLE_DIRS,
-  PREVIEWABLE_ENTRYPOINTS,
-  // task 1002607: the health truth table + the honest no-sandbox wording, pinned.
-  waitHealthy,
-  apiHealthzProbeUrl,
-  NO_SANDBOX_MSG,
-};
-
-if (require.main === module) {
-  cliMain().catch((e) => {
-    console.error('sandbox-stage error:', e.message);
-    process.exit(1);
-  });
-}
+// scripts/gds/sandbox-stage.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/sandbox-stage.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'sandbox-stage.js');