@bongos/core 1.17.0

package/scripts/gds/sandbox-stage.js

@@ -0,0 +1,653 @@
+#!/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.)
+//
+// Two preview contexts (resolvePreviewContext picks one):
+//   - BOX (ADR 0031): box-game-preview.service serves the working tree at
+//     https://sandbox-<login>.amazonprimea.com; "staging" restarts the service.
+//   - LOCAL (task 1056): a builder on a full local clone (laptop) runs the same
+//     ADR 0052 game-only entry privately at http://localhost:<port> via
+//     scripts/gds/local-preview.js; "staging" (re)starts that local process.
+// Either way staging = (re)start the preview to pick up the current working
+// tree, health-check it, record a marker of exactly WHAT tree state was staged,
+// and hand 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) — box AND local alike.
+//
+// Usage (a partial clone 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');
+
+// /etc/otb/box.env exists ONLY on a provisioned dev box (written by box.js
+// provision, #898) — the idiomatic "am I on a box?" marker in this codebase.
+const BOX_ENV_PATH = '/etc/otb/box.env';
+const PREVIEW_WRAPPER = '/usr/local/bin/box-preview';
+const PREVIEW_UNIT = 'box-game-preview.service';
+const HEALTH_URL = 'http://127.0.0.1:3000/';
+const HEALTH_TIMEOUT_MS = 90_000; // first start may run npm ci (ExecStartPre)
+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.
+const PREVIEWABLE_PREFIXES = ['public/', 'src/world/', 'src/rooms/'];
+const PREVIEWABLE_FILES = new Set(['server.js', 'src/preview-server.js']);
+// Same surfaces as git pathspecs (no trailing slash) for scoped plumbing calls.
+const PREVIEWABLE_PATHSPECS = ['public', 'src/world', 'src/rooms', 'server.js', 'src/preview-server.js'];
+
+// On a box, box-game-preview.service has WorkingDirectory=/workspace and serves
+// /workspace/public — the MAIN checkout. A Claude session, though, runs in a git
+// WORKTREE under /workspace/.claude/worktrees/<name>, so its edits never touch
+// /workspace and the sandbox re-served stale code (the #1068 "I don't feel them"
+// bug). We sync the previewable surfaces from the session's branch into this
+// served root before restarting. Kept as a constant so tests can point it at a
+// temp dir.
+const BOX_SERVED_ROOT = '/workspace';
+
+function isDevBox(deps = {}) {
+  const f = deps.fs || fs;
+  return f.existsSync(deps.boxEnvPath || BOX_ENV_PATH);
+}
+
+// Parse BOX_PREVIEW_HOSTNAME out of box.env text. Returns the hostname string
+// or null (a quick-tunnel box has no preview hostname — ADR 0044 §Consequences).
+function readPreviewHostname(envText) {
+  const m = /^\s*(?:export\s+)?BOX_PREVIEW_HOSTNAME=(.*)$/m.exec(String(envText || ''));
+  if (!m) return null;
+  const v = m[1].trim().replace(/^["']|["']$/g, '').trim();
+  return v || null;
+}
+
+function previewUrl(deps = {}) {
+  const f = deps.fs || fs;
+  const p = deps.boxEnvPath || BOX_ENV_PATH;
+  try {
+    const host = readPreviewHostname(f.readFileSync(p, 'utf8'));
+    return host ? `https://${host}` : null;
+  } catch {
+    return null;
+  }
+}
+
+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 dev box OR a local game
+// preview). The decision is identical for both; only HOW we stage + the URL differ.
+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 (not a dev box; 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 (quick-tunnel box / 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' };
+}
+
+function restartPreview(deps = {}) {
+  const run = deps.execFileSync || execFileSync;
+  const f = deps.fs || fs;
+  // The baked wrapper is the expected path on every box (cloud-init +
+  // box-source-fetch self-heal bake it to /usr/local/bin, and it handles its
+  // own sudo). The raw systemctl branch is only a degraded fallback.
+  if (f.existsSync(deps.previewWrapper || PREVIEW_WRAPPER)) {
+    run(deps.previewWrapper || PREVIEW_WRAPPER, ['restart'], { stdio: 'inherit' });
+    return;
+  }
+  const needSudo = typeof process.getuid === 'function' && process.getuid() !== 0;
+  const cmd = needSudo ? 'sudo' : 'systemctl';
+  const argv = needSudo ? ['-n', 'systemctl', 'restart', PREVIEW_UNIT] : ['restart', PREVIEW_UNIT];
+  run(cmd, argv, { stdio: 'inherit' });
+}
+
+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) });
+      if (res.status < 500) 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 };
+}
+
+// The git checkout the session is editing. On a box this is a linked worktree
+// under /workspace/.claude/worktrees/<name>; on a laptop it's the clone root.
+// Returns the toplevel path or null (not a repo).
+function sessionCheckoutRoot(deps = {}) {
+  const run = deps.execFileSync || execFileSync;
+  const cwd = deps.cwd || process.cwd();
+  try {
+    return run('git', ['rev-parse', '--show-toplevel'], { cwd, encoding: 'utf8' }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Box-only (#1068 gap 1): materialize the session worktree's previewable game
+// surfaces into the served checkout (/workspace) so the box preview shows the
+// SESSION's edits, not stale main. The served root and the worktree share one
+// object store (linked worktree), so `git -C /workspace checkout <branch> -- <paths>`
+// brings the branch's committed content for exactly the previewable pathspecs.
+// ship.js preflight already proved the worktree is clean (committed == working
+// tree), so committed content is what the builder means. No-op when the session
+// checkout IS the served root (a box where the builder edits /workspace directly,
+// or a laptop). Returns { ok, synced, reason?, branch? }.
+// Canonicalize a path through symlinks for a same-directory comparison. Needed
+// because `git rev-parse --show-toplevel` (sessionCheckoutRoot) returns the REAL
+// path, while servedRoot may be a symlink — on macOS `/tmp` -> `/private/var`
+// (idea #278), or any symlinked served root. path.resolve does NOT resolve
+// symlinks, so the raw comparison false-negatives "same dir" and the code would
+// wrongly try to git-sync a checkout onto itself. Falls back to path.resolve when
+// the path doesn't exist yet (realpathSync throws ENOENT).
+function realPathOr(p) {
+  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+}
+
+function syncWorktreeToServed(deps = {}) {
+  const run = deps.execFileSync || execFileSync;
+  const servedRoot = deps.servedRoot || BOX_SERVED_ROOT;
+  const sessionRoot = sessionCheckoutRoot(deps);
+  if (!sessionRoot || realPathOr(sessionRoot) === realPathOr(servedRoot)) {
+    return { ok: true, synced: false, reason: 'session checkout is the served checkout' };
+  }
+  let branch;
+  try {
+    branch = run('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: sessionRoot, encoding: 'utf8' }).trim();
+  } catch {
+    branch = null;
+  }
+  if (!branch || branch === 'HEAD') {
+    return { ok: false, synced: false, reason: 'could not resolve the session branch (detached HEAD?)' };
+  }
+  // Check out each previewable pathspec INDEPENDENTLY: `git checkout <ref> -- a b c`
+  // fails ENTIRELY if any single pathspec is absent from the ref, and a sparse
+  // box (STARTER_SPARSE_PATHS) may legitimately lack server.js / src/preview-server.js.
+  // Per-pathspec lets us sync what exists and skip what doesn't; verifyServedFresh
+  // is the safety net that catches a sync that didn't actually land. First restore
+  // each path from the served checkout's own HEAD (undo any prior ship's leftovers),
+  // then overlay the session branch's content.
+  let synced = false;
+  let lastErr = null;
+  for (const ps of PREVIEWABLE_PATHSPECS) {
+    try {
+      run('git', ['-C', servedRoot, 'checkout', '--', ps], { stdio: 'ignore' });
+    } catch {
+      /* pathspec absent in the served HEAD — nothing to restore, fine */
+    }
+    try {
+      run('git', ['-C', servedRoot, 'checkout', branch, '--', ps], { stdio: 'ignore' });
+      synced = true;
+    } catch (e) {
+      lastErr = e; // pathspec absent in the branch (sparse/missing) — skip it
+    }
+  }
+  if (!synced) {
+    return { ok: false, synced: false, reason: `git checkout ${branch} -- <previewable> in ${servedRoot} synced nothing${lastErr ? ` (${lastErr.message})` : ''}` };
+  }
+  return { ok: true, synced: true, branch };
+}
+
+// Pick the smallest cheap-to-compare changed previewable static file to verify,
+// and the URL path the preview serves it at (public/game/x.js -> /game/x.js).
+// Returns { relPath, urlPath } or null when there's no served static change.
+function pickVerifyTarget(deps = {}) {
+  const run = deps.execFileSync || execFileSync;
+  const cwd = deps.cwd || process.cwd();
+  const f = deps.fs || fs;
+  try {
+    const out = run('git', ['status', '--porcelain', '--', 'public'], { cwd, encoding: 'utf8' });
+    let chosen = out
+      .split('\n')
+      .map((line) => line.slice(3).replace(/^"|"$/g, '').trim())
+      .find((rel) => rel && rel.startsWith('public/') && f.existsSync(path.join(cwd, rel)));
+    if (!chosen) {
+      // committed-only change: fall back to the diff vs the frozen origin/main
+      const diff = run('git', ['diff', '--name-only', 'origin/main...HEAD', '--', 'public'], { cwd, encoding: 'utf8' });
+      chosen = diff
+        .split('\n')
+        .map((s) => s.trim())
+        .find((p) => p.startsWith('public/') && f.existsSync(path.join(cwd, p)));
+    }
+    if (!chosen) return null;
+    return { relPath: chosen, urlPath: '/' + chosen.replace(/^public\//, '') };
+  } catch {
+    return null;
+  }
+}
+
+// Box-only (#1068 gap 1b): after staging, fetch one changed static file from the
+// RUNNING preview over loopback (bypasses Cloudflare + browser cache, so it
+// proves the SERVER is fresh) and confirm it byte-matches the worktree. Returns
+// { ok, verified?|skipped?, reason? }. A mismatch means the sandbox is serving
+// stale code despite the restart — fail loudly.
+async function verifyServedFresh(deps = {}) {
+  const fetchImpl = deps.fetchImpl || fetch;
+  const f = deps.fs || fs;
+  const cwd = deps.cwd || process.cwd();
+  const base = (deps.healthUrl || HEALTH_URL).replace(/\/$/, '');
+  const target = pickVerifyTarget(deps);
+  if (!target) return { ok: true, skipped: true, reason: 'no served static change to verify (e.g. only src/rooms changed)' };
+  let want;
+  try {
+    want = f.readFileSync(path.join(cwd, target.relPath), 'utf8');
+  } catch {
+    return { ok: true, skipped: true, reason: 'could not read the worktree file to compare' };
+  }
+  try {
+    const res = await fetchImpl(`${base}${target.urlPath}`, {
+      headers: { 'Cache-Control': 'no-cache' },
+      signal: AbortSignal.timeout(5_000),
+    });
+    if (res.status >= 400) return { ok: false, reason: `preview returned HTTP ${res.status} for ${target.urlPath}` };
+    const got = await res.text();
+    if (got === want) return { ok: true, verified: target.relPath };
+    return { ok: false, reason: `served ${target.urlPath} does NOT match your worktree ${target.relPath} — the sandbox is serving stale code` };
+  } catch (e) {
+    return { ok: false, reason: `could not fetch ${target.urlPath} from the running preview to verify freshness: ${e.message}` };
+  }
+}
+
+// Which sandbox does this machine have? A box (ADR 0044) is keyed by ANY box
+// marker (localPreview.onBox: box.env, the box-preview wrapper, or the
+// box-game-preview.service unit — broader than box.env alone so a box with a
+// lost/unreadable box.env is STILL routed to the box branch, never to localhost
+// — task 1443); 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 partial clone with no game). On a box the url comes from box.env's
+// BOX_PREVIEW_HOSTNAME; if that's missing the url is null and stage() returns a
+// clear "no sandbox hostname" message — but it is NEVER a localhost URL the
+// builder's browser can't reach. deps.previewContext short-circuits for
+// hermetic tests. The box branch is checked FIRST: a box also has the game
+// entry, so order is what keeps onBox from being shadowed by hasGameEntry.
+function resolvePreviewContext(deps = {}) {
+  if (deps.previewContext !== undefined) return deps.previewContext;
+  if (localPreview.onBox(deps)) {
+    return {
+      kind: 'box',
+      url: previewUrl(deps),
+      healthUrl: HEALTH_URL,
+      restart: (d) => restartPreview(d),
+    };
+  }
+  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 (not a dev box, and this clone has no local game preview)' };
+  if (!ctx.url) {
+    return { ok: false, reason: ctx.kind === 'box'
+      ? 'no sandbox hostname on this box — box.env has no BOX_PREVIEW_HOSTNAME (a quick-tunnel box, or box.env is missing/unreadable). Run `box-preview status` for your URL, or ask the operator to re-provision with BOX_NAMED_TUNNEL=1 (ADR 0044). NOT a localhost link — that is unreachable from your browser on a box.'
+      : 'local preview URL unavailable' };
+  }
+  console.log(ctx.kind === 'local'
+    ? 'Staging your working tree on your local sandbox (starting the game preview)...'
+    : 'Staging your working tree on the sandbox (syncing your worktree, then restarting the game preview)...');
+  // #1068 gap 1: a box serves /workspace, not the session worktree. Sync the
+  // previewable surfaces from the branch into /workspace BEFORE the restart so
+  // the preview picks up the SESSION's edits. hard:true → the ship gate aborts
+  // (a stale sandbox review is worse than no review). Local already serves the
+  // worktree, so this is box-only.
+  if (ctx.kind === 'box') {
+    const sync = (deps.syncWorktreeToServed || syncWorktreeToServed)(deps);
+    if (!sync.ok) {
+      return { ok: false, hard: true, reason: `could not sync your worktree to the served checkout (${sync.reason}); the sandbox would show stale ${deps.servedRoot || BOX_SERVED_ROOT} code` };
+    }
+    if (sync.synced) console.log(`  synced previewable surfaces from ${sync.branch} into ${deps.servedRoot || BOX_SERVED_ROOT}`);
+  }
+  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) {
+    const where = ctx.kind === 'local' ? 'node scripts/gds/local-preview.js logs' : 'box-preview logs';
+    return { ok: false, reason: `preview did not come up healthy (${health.reason}) — check '${where}'` };
+  }
+  // #1068 gap 1b: confirm the restarted box preview is actually serving the
+  // synced bytes (loopback fetch, cache-bypassed). A mismatch is a hard fail —
+  // claiming "staged" when the sandbox shows stale code is the bug we're killing.
+  if (ctx.kind === 'box') {
+    const v = await (deps.verifyServedFresh || verifyServedFresh)({ ...deps, healthUrl: ctx.healthUrl });
+    if (!v.ok) {
+      return { ok: false, hard: true, reason: `staged but FAILED freshness verification: ${v.reason}` };
+    }
+    if (v.verified) console.log(`  verified the sandbox is serving your edits (${v.verified} matches)`);
+    else if (v.skipped) console.log(`  freshness verify skipped (${v.reason})`);
+  }
+  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. Works for a box (sandbox-<login>) or a
+// local clone (http://localhost:<port>) — the URL 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 (box OR local), 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) — for a box or a local
+// clone (task 1056).
+//
+// `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) {
+    // #1068: a HARD failure (couldn't sync the worktree to the served checkout,
+    // or the preview verifiably served stale code) means a review here would be
+    // a LIE — abort with the claim intact so the builder fixes it. A SOFT
+    // failure (the preview simply didn't come up) must not brick shipping — the
+    // gate is a review aid, not a wall: warn loudly and continue.
+    if (staged.hard) {
+      return {
+        ok: false,
+        review: true,
+        url: staged.url,
+        reason: `sandbox staging could not be trusted (${staged.reason}) — fix it, then re-run /builder-ship (or --skip-stage to bypass the review). Your claim is still active`,
+      };
+    }
+    console.error(`warn: sandbox staging failed (${staged.reason}); continuing without the review step.`);
+    return { ok: true };
+  }
+
+  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) };
+}
+
+async function cliMain() {
+  const cmd = process.argv[2] || 'stage';
+  const ctx = resolvePreviewContext();
+  const NO_SANDBOX = 'No sandbox here — not a dev box, and this clone has no game preview entry (src/preview-server.js).';
+
+  if (cmd === 'url') {
+    console.log(ctx && ctx.url ? ctx.url : '(no sandbox here — not a dev box, and no local game preview in this clone)');
+    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 — quick-tunnel box)'}`);
+    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) {
+    console.log(NO_SANDBOX);
+    console.log('A full local clone gets a private localhost preview; a partial clone does not.');
+    return;
+  }
+  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 = {
+  isDevBox,
+  readPreviewHostname,
+  previewUrl,
+  isPreviewableFile,
+  anyPreviewable,
+  computeTreeStamp,
+  workingTreePreviewable,
+  markerPath,
+  readMarker,
+  writeMarker,
+  decideShipGate,
+  resolvePreviewContext,
+  stage,
+  runShipGate,
+  BOX_ENV_PATH,
+  BOX_SERVED_ROOT,
+  PREVIEWABLE_PATHSPECS,
+  sessionCheckoutRoot,
+  syncWorktreeToServed,
+  pickVerifyTarget,
+  verifyServedFresh,
+};
+
+if (require.main === module) {
+  cliMain().catch((e) => {
+    console.error('sandbox-stage error:', e.message);
+    process.exit(1);
+  });
+}