@bongos/core 1.21.174 → 1.21.176

package/scripts/bongos/runner-drift.js

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos/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.
+'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));

package/scripts/bongos/sandbox-stage.js

@@ -0,0 +1,459 @@
+#!/usr/bin/env node
+// scripts/bongos/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/bongos/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/bongos/sandbox-stage.js            # stage + print the review URL
+//   node scripts/bongos/sandbox-stage.js status     # preview state + is the marker current?
+//   node scripts/bongos/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/bongos/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/bongos/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);
+  });
+}