@bongos/core 1.17.0

package/tests/sandbox_stage.mjs

@@ -0,0 +1,582 @@
+// tests/sandbox_stage.mjs
+//
+// Hermetic unit smoke for scripts/gds/sandbox-stage.js — the sandbox-first
+// review step (#927, ADR 0046) that ship.js runs before resolving a claim, on a
+// dev box (ADR 0044) OR a local full clone (task 1056). Covers: box detection,
+// BOX_PREVIEW_HOSTNAME parsing, previewable-surface matching, the decideShipGate
+// decision table, resolvePreviewContext (box/local/none), marker round-trip +
+// tree-stamp freshness (real temp git repo), the runShipGate composition with
+// injected fs/exec/prompt, and the recorded self-approval (#1048) for box AND
+// local. NO network, NO systemd, NO real box.
+//
+// Run:  node tests/sandbox_stage.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+const require = createRequire(import.meta.url);
+const sbx = require('../scripts/gds/sandbox-stage.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); }
+}
+
+// ---------- isDevBox ----------
+t('isDevBox: true only when box.env exists', () => {
+  assert.equal(sbx.isDevBox({ fs: { existsSync: (p) => p === '/etc/otb/box.env' } }), true);
+  assert.equal(sbx.isDevBox({ fs: { existsSync: () => false } }), false);
+});
+
+// ---------- readPreviewHostname ----------
+t('readPreviewHostname: plain, quoted, export-prefixed, missing, empty', () => {
+  assert.equal(sbx.readPreviewHostname('BOX_PREVIEW_HOSTNAME=sandbox-somebuilder.amazonprimea.com\n'), 'sandbox-somebuilder.amazonprimea.com');
+  assert.equal(sbx.readPreviewHostname('A=1\nBOX_PREVIEW_HOSTNAME="sandbox-x.example.com"\nB=2'), 'sandbox-x.example.com');
+  assert.equal(sbx.readPreviewHostname("export BOX_PREVIEW_HOSTNAME='sandbox-y.example.com'"), 'sandbox-y.example.com');
+  assert.equal(sbx.readPreviewHostname('BOX_TERMINAL_HOSTNAME=term-x.example.com'), null);
+  assert.equal(sbx.readPreviewHostname('BOX_PREVIEW_HOSTNAME='), null);
+  assert.equal(sbx.readPreviewHostname(''), null);
+  assert.equal(sbx.readPreviewHostname(null), null);
+});
+
+t('previewUrl: reads box.env via injected fs; null when unreadable', () => {
+  const deps = { fs: { readFileSync: () => 'BOX_PREVIEW_HOSTNAME=sandbox-z.example.com\n' } };
+  assert.equal(sbx.previewUrl(deps), 'https://sandbox-z.example.com');
+  assert.equal(sbx.previewUrl({ fs: { readFileSync: () => { throw new Error('ENOENT'); } } }), null);
+});
+
+// ---------- previewable surfaces ----------
+t('isPreviewableFile: game surfaces yes, internal surfaces no', () => {
+  for (const f of ['public/game/main.js', 'src/world/terrain.js', 'src/rooms/WorldRoom.js', 'server.js']) {
+    assert.equal(sbx.isPreviewableFile(f), true, `${f} should be previewable`);
+  }
+  for (const f of ['scripts/gds/ship.js', 'modules/dev-box/routes/box.js', 'docs/adr/0046.md', 'modules/status-ui/public/index.html', 'modules/hall-ui/public/hall.js', 'migrations/075.sql', 'tests/sandbox_stage.mjs', 'server.js.bak']) {
+    assert.equal(sbx.isPreviewableFile(f), false, `${f} should NOT be previewable`);
+  }
+});
+
+t('anyPreviewable: mixed diff counts as previewable; empty/none does not', () => {
+  assert.equal(sbx.anyPreviewable(['docs/x.md', 'public/game/a.js']), true);
+  assert.equal(sbx.anyPreviewable(['docs/x.md', 'scripts/gds/y.js']), false);
+  assert.equal(sbx.anyPreviewable([]), false);
+  assert.equal(sbx.anyPreviewable(null), false);
+});
+
+// ---------- decideShipGate decision table ----------
+t('decideShipGate: full decision table', () => {
+  // gateActive = a sandbox exists here (a dev box OR a local game preview). The
+  // table is identical for both; only HOW we stage + the URL differ downstream.
+  const base = { gateActive: true, previewUrl: 'https://sandbox-x', previewable: true, stagedFresh: false, tty: true, skipStage: false };
+  assert.equal(sbx.decideShipGate({ ...base, skipStage: true }).action, 'skip');
+  assert.equal(sbx.decideShipGate({ ...base, gateActive: false }).action, 'skip');
+  assert.equal(sbx.decideShipGate({ ...base, previewable: false }).action, 'skip');
+  assert.equal(sbx.decideShipGate({ ...base, previewUrl: null }).action, 'skip');
+  assert.equal(sbx.decideShipGate({ ...base, stagedFresh: true }).action, 'pass');
+  assert.equal(sbx.decideShipGate(base).action, 'review');
+  assert.equal(sbx.decideShipGate({ ...base, tty: false }).action, 'stage_abort');
+  // a fresh marker passes even non-interactively (the re-run after review)
+  assert.equal(sbx.decideShipGate({ ...base, tty: false, stagedFresh: true }).action, 'pass');
+  // precedence: skipStage wins even when everything else says review
+  assert.equal(sbx.decideShipGate({ ...base, skipStage: true, stagedFresh: true }).action, 'skip');
+});
+
+// ---------- resolvePreviewContext: box vs local vs none (task 1056) ----------
+t('resolvePreviewContext: dev box → box kind with the named-tunnel URL', () => {
+  const ctx = sbx.resolvePreviewContext({
+    fs: {
+      existsSync: (p) => p === sbx.BOX_ENV_PATH,
+      readFileSync: () => 'BOX_PREVIEW_HOSTNAME=sandbox-x.example.com\n',
+    },
+  });
+  assert.equal(ctx.kind, 'box');
+  assert.equal(ctx.url, 'https://sandbox-x.example.com');
+});
+
+t('resolvePreviewContext: local full clone (no box, game entry present) → local kind at localhost', () => {
+  const gameEntryFs = { existsSync: (p) => p !== sbx.BOX_ENV_PATH && /preview-server\.js$/.test(String(p)) };
+  const ctx = sbx.resolvePreviewContext({ env: {}, fs: gameEntryFs });
+  assert.equal(ctx.kind, 'local');
+  assert.equal(ctx.url, 'http://localhost:3100');
+  // honors OTB_PREVIEW_PORT so it can dodge a locally-running full server
+  const ctx2 = sbx.resolvePreviewContext({ env: { OTB_PREVIEW_PORT: '4200' }, fs: gameEntryFs });
+  assert.equal(ctx2.url, 'http://localhost:4200');
+});
+
+t('resolvePreviewContext: partial clone (no box, no game entry) → null (no sandbox)', () => {
+  assert.equal(sbx.resolvePreviewContext({ fs: { existsSync: () => false } }), null);
+});
+
+// task 1443: a box whose box.env is missing/unreadable must STILL be detected as
+// a box (via the box-preview wrapper or the service unit) and must NEVER fall
+// through to the localhost local-preview branch — localhost is unreachable from
+// the builder's browser on a remote box.
+t('resolvePreviewContext: box via the box-preview wrapper + unreadable box.env → box kind, NEVER localhost', () => {
+  const ctx = sbx.resolvePreviewContext({
+    fs: {
+      // wrapper present (a box) + game entry present (a box has the game), but box.env unreadable
+      existsSync: (p) => p === '/usr/local/bin/box-preview' || /preview-server\.js$/.test(String(p)),
+      readFileSync: () => { throw new Error('EACCES'); },
+    },
+  });
+  assert.equal(ctx.kind, 'box', 'a box marker wins over hasGameEntry → box branch, not local');
+  assert.equal(ctx.url, null, 'no readable hostname → null url (stage gives a clear message), never a localhost URL');
+});
+
+t('resolvePreviewContext: box via the box-game-preview.service unit → box kind', () => {
+  const ctx = sbx.resolvePreviewContext({
+    fs: {
+      existsSync: (p) => p === '/etc/systemd/system/box-game-preview.service',
+      readFileSync: () => { throw new Error('ENOENT'); },
+    },
+  });
+  assert.equal(ctx.kind, 'box');
+  assert.equal(ctx.url, null);
+});
+
+await ta('stage: box with no readable hostname → clear "no sandbox hostname" message, not a localhost link', async () => {
+  const staged = await sbx.stage({ taskId: 1443 }, {
+    fs: { existsSync: (p) => p === '/usr/local/bin/box-preview', readFileSync: () => { throw new Error('EACCES'); } },
+  });
+  assert.equal(staged.ok, false);
+  assert.match(staged.reason, /no sandbox hostname/i);
+  assert.match(staged.reason, /box-preview status/);
+  assert.doesNotMatch(staged.reason, /http:\/\/localhost/, 'must not hand back a localhost URL on a box');
+});
+
+// ---------- tree stamp + marker (real temp git repo) ----------
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-sbx-test-'));
+// Markers live OUTSIDE the repo — on a real box the marker is in /tmp, not
+// /workspace, so it must never perturb the tree stamp it certifies.
+const markerDir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-sbx-markers-'));
+function git(...args) { execFileSync('git', args, { cwd: tmp, encoding: 'utf8' }); }
+git('init', '-q');
+git('config', 'user.email', 'test@example.com');
+git('config', 'user.name', 'test');
+fs.mkdirSync(path.join(tmp, 'public'));
+fs.mkdirSync(path.join(tmp, 'docs'));
+fs.writeFileSync(path.join(tmp, 'public', 'game.js'), 'one\n');
+fs.writeFileSync(path.join(tmp, 'server.js'), 'srv\n');
+fs.writeFileSync(path.join(tmp, 'docs', 'notes.md'), 'doc\n');
+git('add', '.');
+git('commit', '-qm', 'init');
+
+t('computeTreeStamp: content-stable, scoped to game surfaces', () => {
+  const s1 = sbx.computeTreeStamp({ cwd: tmp });
+  const s2 = sbx.computeTreeStamp({ cwd: tmp });
+  assert.ok(s1 && /^[0-9a-f]{64}$/.test(s1));
+  assert.equal(s1, s2, 'same tree → same stamp');
+
+  // Non-previewable edits must NOT invalidate a staged review.
+  fs.writeFileSync(path.join(tmp, 'docs', 'notes.md'), 'doc edited\n');
+  assert.equal(sbx.computeTreeStamp({ cwd: tmp }), s1, 'docs edit → stamp unchanged');
+
+  // A game-surface edit produces a new stamp...
+  fs.writeFileSync(path.join(tmp, 'public', 'game.js'), 'two\n');
+  const s3 = sbx.computeTreeStamp({ cwd: tmp });
+  assert.notEqual(s3, s1, 'game edit → new stamp');
+
+  // ...and committing that SAME content keeps the stamp (content-stable), so
+  // the natural stage → review → commit → ship flow stays fresh.
+  git('add', '.');
+  git('commit', '-qm', 'edit');
+  assert.equal(sbx.computeTreeStamp({ cwd: tmp }), s3, 'commit of same content → stamp unchanged');
+
+  // An untracked game file counts.
+  fs.writeFileSync(path.join(tmp, 'public', 'new-tile.js'), 'untracked\n');
+  const s4 = sbx.computeTreeStamp({ cwd: tmp });
+  assert.notEqual(s4, s3, 'untracked game file → new stamp');
+  fs.rmSync(path.join(tmp, 'public', 'new-tile.js'));
+  assert.equal(sbx.computeTreeStamp({ cwd: tmp }), s3, 'removing it restores the stamp');
+
+  assert.equal(sbx.computeTreeStamp({ cwd: os.tmpdir() }), null, 'not a repo → null');
+});
+
+t('workingTreePreviewable: dirty game surface yes, dirty docs no', () => {
+  assert.equal(sbx.workingTreePreviewable({ cwd: tmp }), false, 'clean previewable surfaces (docs dirt ignored)');
+  fs.writeFileSync(path.join(tmp, 'server.js'), 'srv edited\n');
+  assert.equal(sbx.workingTreePreviewable({ cwd: tmp }), true, 'dirty server.js detected');
+  git('checkout', '--', 'server.js');
+  assert.equal(sbx.workingTreePreviewable({ cwd: tmp }), false);
+});
+
+// Clean the tree before the runShipGate scenarios so previewable detection is
+// driven purely by the `files` each test passes in.
+git('add', '.');
+git('commit', '--allow-empty', '-qm', 'clean before gate tests');
+
+t('marker: round-trip via injected path; unreadable → null', () => {
+  const mp = path.join(markerDir, 'marker.json');
+  const deps = { markerPath: mp };
+  assert.equal(sbx.readMarker(deps), null);
+  sbx.writeMarker({ stamp: 'abc', url: 'https://sandbox-x', task_id: 927 }, deps);
+  const m = sbx.readMarker(deps);
+  assert.equal(m.stamp, 'abc');
+  assert.equal(m.task_id, 927);
+});
+
+// ---------- runShipGate composition (BOX) ----------
+// Fake "box" deps: box.env exists + carries a preview hostname; restart is a
+// no-op; health answers 200 immediately; marker lives in the temp dir.
+function boxDeps(markerFile, overrides = {}) {
+  return {
+    fs: {
+      existsSync: (p) => p === '/etc/otb/box.env' || fs.existsSync(p),
+      readFileSync: (p, enc) => p === '/etc/otb/box.env'
+        ? 'BOX_PREVIEW_HOSTNAME=sandbox-test.example.com\n'
+        : fs.readFileSync(p, enc),
+      writeFileSync: (p, d) => fs.writeFileSync(p, d),
+    },
+    execFileSync: (cmd, args, opts) => {
+      // git goes through for real (the temp repo); systemctl/box-preview no-op.
+      if (cmd === 'git') return execFileSync(cmd, args, opts);
+      return '';
+    },
+    fetchImpl: async () => ({ status: 200 }),
+    markerPath: markerFile,
+    cwd: tmp,
+    pollMs: 1,
+    timeoutMs: 1000,
+    previewWrapper: '/nonexistent-box-preview',
+    // #1068: the box stage() now syncs the worktree into /workspace + verifies
+    // the served bytes. Inject no-ops here so the gate-composition tests don't
+    // touch the real /workspace or need a text()-capable fetch mock — the real
+    // syncWorktreeToServed / verifyServedFresh get their OWN dedicated tests.
+    syncWorktreeToServed: () => ({ ok: true, synced: false }),
+    verifyServedFresh: async () => ({ ok: true, skipped: true }),
+    ...overrides,
+  };
+}
+
+await ta('runShipGate: no sandbox available (not a box, no local game entry) → ok, no staging', async () => {
+  // existsSync()=>false means neither /etc/otb/box.env NOR src/preview-server.js
+  // is present — a partial clone with no game. (A full local clone WITH the game
+  // is covered by the LOCAL tests below, where it DOES stage.)
+  const r = await sbx.runShipGate(
+    { taskId: 1, files: ['public/game/a.js'], skipStage: false, tty: true },
+    { fs: { existsSync: () => false } }
+  );
+  assert.equal(r.ok, true);
+});
+
+await ta('runShipGate: box + non-game diff → ok, no staging', async () => {
+  const mp = path.join(markerDir, 'm1.json');
+  const r = await sbx.runShipGate({ taskId: 1, files: ['docs/x.md'], skipStage: false, tty: true }, boxDeps(mp));
+  assert.equal(r.ok, true);
+  assert.equal(fs.existsSync(mp), false, 'no marker written — nothing staged');
+});
+
+await ta('runShipGate: box + game diff + TTY, reviewer says yes → stages then ok, records tty sign-off', async () => {
+  const mp = path.join(markerDir, 'm2.json');
+  const deps = boxDeps(mp, { promptYesNo: async () => true });
+  const r = await sbx.runShipGate({ taskId: 927, files: ['src/world/terrain.js'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, true);
+  const m = JSON.parse(fs.readFileSync(mp, 'utf8'));
+  assert.equal(m.url, 'https://sandbox-test.example.com');
+  assert.ok(m.stamp, 'marker carries the staged tree stamp');
+  // #1048: a TTY 'y' IS the explicit sign-off → recorded as method 'tty'.
+  assert.equal(r.sandboxReview.method, 'tty', 'TTY yes records a tty sign-off');
+  assert.equal(r.sandboxReview.url, 'https://sandbox-test.example.com');
+  assert.ok(r.sandboxReview.stamp, 'approval record carries the reviewed tree stamp');
+});
+
+await ta('runShipGate: reviewer says NO → aborts with claim-preserving reason', async () => {
+  const mp = path.join(markerDir, 'm3.json');
+  const deps = boxDeps(mp, { promptYesNo: async () => false });
+  const r = await sbx.runShipGate({ taskId: 927, files: ['public/game/a.js'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /sandbox review declined/);
+});
+
+await ta('runShipGate: fresh marker → pass without prompting', async () => {
+  const mp = path.join(markerDir, 'm4.json');
+  const deps = boxDeps(mp, { promptYesNo: async () => { throw new Error('must not prompt'); } });
+  sbx.writeMarker({ stamp: sbx.computeTreeStamp({ cwd: tmp }), url: 'https://sandbox-test.example.com' }, deps);
+  const r = await sbx.runShipGate({ taskId: 927, files: ['server.js'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, true);
+});
+
+await ta('runShipGate: stale marker forces a re-stage (stamp mismatch)', async () => {
+  const mp = path.join(markerDir, 'm5.json');
+  let prompted = false;
+  const deps = boxDeps(mp, { promptYesNo: async () => { prompted = true; return true; } });
+  sbx.writeMarker({ stamp: 'stale-stamp', url: 'https://sandbox-test.example.com' }, deps);
+  const r = await sbx.runShipGate({ taskId: 927, files: ['server.js'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, true);
+  assert.equal(prompted, true, 'stale stamp must re-stage + re-prompt');
+});
+
+await ta('runShipGate: non-TTY → stages then ABORTS with the review URL (no prompt, no hang)', async () => {
+  const mp = path.join(markerDir, 'm6.json');
+  const deps = boxDeps(mp, { promptYesNo: async () => { throw new Error('must not prompt'); } });
+  const r = await sbx.runShipGate({ taskId: 927, files: ['public/game/a.js'], skipStage: false, tty: false }, deps);
+  assert.equal(r.ok, false, 'unreviewed game work must not ship non-interactively');
+  assert.equal(r.review, true, 'abort is flagged as a review pause');
+  assert.match(r.reason, /staged at https:\/\/sandbox-test\.example\.com/i);
+  assert.ok(fs.existsSync(mp), 'work is staged so the human can review at the URL');
+  // ...and after the (notional) review, a bare re-run passes on the fresh marker
+  // but records NO sign-off (no --approved) — back-compat / failure-open.
+  const r2 = await sbx.runShipGate({ taskId: 927, files: ['public/game/a.js'], skipStage: false, tty: false }, deps);
+  assert.equal(r2.ok, true, 're-run after staging passes (marker fresh)');
+  assert.equal(r2.sandboxReview, undefined, 'bare re-run records no sign-off');
+});
+
+await ta('runShipGate: uncommitted game edit counts as previewable even when committed diff does not', async () => {
+  const mp = path.join(markerDir, 'm9.json');
+  const deps = boxDeps(mp, { promptYesNo: async () => true });
+  fs.writeFileSync(path.join(tmp, 'public', 'game.js'), 'dirty working tree\n');
+  const r = await sbx.runShipGate({ taskId: 927, files: ['docs/x.md'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, true);
+  assert.ok(fs.existsSync(mp), 'gate staged the dirty game surface');
+  git('checkout', '--', 'public/game.js');
+});
+
+await ta('runShipGate: --skip-stage → ok, untouched', async () => {
+  const mp = path.join(markerDir, 'm7.json');
+  const r = await sbx.runShipGate({ taskId: 927, files: ['public/game/a.js'], skipStage: true, tty: true }, boxDeps(mp));
+  assert.equal(r.ok, true);
+  assert.equal(fs.existsSync(mp), false);
+});
+
+await ta('runShipGate: staging failure (health never green) warns but does not block', async () => {
+  const mp = path.join(markerDir, 'm8.json');
+  const deps = boxDeps(mp, { fetchImpl: async () => ({ status: 502 }), timeoutMs: 10 });
+  const r = await sbx.runShipGate({ taskId: 927, files: ['public/game/a.js'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, true, 'a broken preview must not brick shipping');
+});
+
+// ---------- recorded self-approval (#1048), box ----------
+await ta('runShipGate: --approved re-run on a fresh stage records a flag sign-off (#1048)', async () => {
+  const mp = path.join(markerDir, 'm10.json');
+  const deps = boxDeps(mp, { promptYesNo: async () => { throw new Error('must not prompt'); } });
+  // Simulate "already staged + reviewed on a prior run": fresh marker, then the
+  // builder approves via the flag on the re-run.
+  sbx.writeMarker({ stamp: sbx.computeTreeStamp({ cwd: tmp }), url: 'https://sandbox-test.example.com' }, deps);
+  const r = await sbx.runShipGate({ taskId: 1048, files: ['server.js'], skipStage: false, tty: false, approved: true }, deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.sandboxReview.method, 'flag', 'approved re-run records a flag sign-off');
+  assert.equal(r.sandboxReview.url, 'https://sandbox-test.example.com');
+  assert.ok(r.sandboxReview.stamp, 'record carries the reviewed tree stamp');
+});
+
+await ta('runShipGate: --approved cannot pre-approve an UNstaged change (still stage_aborts)', async () => {
+  const mp = path.join(markerDir, 'm11.json');
+  const deps = boxDeps(mp, { promptYesNo: async () => { throw new Error('must not prompt'); } });
+  // No marker → not staged-fresh → --approved is ignored; the gate still stages
+  // + aborts for review. You cannot sign off on something never shown.
+  const r = await sbx.runShipGate({ taskId: 1048, files: ['public/game/a.js'], skipStage: false, tty: false, approved: true }, deps);
+  assert.equal(r.ok, false, '--approved must not bypass the first stage + review');
+  assert.equal(r.review, true);
+  assert.equal(r.sandboxReview, undefined, 'nothing recorded — nothing was staged to approve');
+});
+
+// ---------- #1068: worktree → served sync + freshness verify ----------
+
+// A box serves /workspace (the MAIN checkout), but a session edits a linked
+// worktree. syncWorktreeToServed must materialize the branch's previewable
+// content into the served root. Build a real main checkout + a `git worktree`
+// off a feature branch that changed public/game.js, then assert the served copy
+// gets the branch content.
+await ta('syncWorktreeToServed: brings the branch content into the served checkout', async () => {
+  const served = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-served-'));
+  const g = (...a) => execFileSync('git', a, { cwd: served, encoding: 'utf8' });
+  g('init', '-q');
+  g('config', 'user.email', 't@e.com'); g('config', 'user.name', 't');
+  fs.mkdirSync(path.join(served, 'public'));
+  fs.writeFileSync(path.join(served, 'public', 'game.js'), 'MAIN content\n');
+  g('add', '.'); g('commit', '-qm', 'main');
+  // a linked worktree on a feature branch with different game content
+  const wt = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-wt-')) + '/co';
+  g('worktree', 'add', '-q', '-b', 'claude/feat', wt);
+  fs.writeFileSync(path.join(wt, 'public', 'game.js'), 'BRANCH content\n');
+  execFileSync('git', ['add', '.'], { cwd: wt });
+  execFileSync('git', ['commit', '-qm', 'branch edit'], { cwd: wt });
+
+  const r = sbx.syncWorktreeToServed({ cwd: wt, servedRoot: served });
+  assert.equal(r.ok, true);
+  assert.equal(r.synced, true);
+  assert.equal(r.branch, 'claude/feat');
+  assert.equal(fs.readFileSync(path.join(served, 'public', 'game.js'), 'utf8'), 'BRANCH content\n',
+    'served /workspace now shows the SESSION branch content, not stale main');
+
+  g('worktree', 'remove', '--force', wt);
+  fs.rmSync(served, { recursive: true, force: true });
+});
+
+t('syncWorktreeToServed: no-op when the session checkout IS the served root', () => {
+  const r = sbx.syncWorktreeToServed({ cwd: tmp, servedRoot: tmp });
+  assert.equal(r.ok, true);
+  assert.equal(r.synced, false);
+});
+
+t('syncWorktreeToServed: a SYMLINKED servedRoot pointing at the session checkout is a no-op (idea #278)', () => {
+  // The macOS footgun: `git rev-parse --show-toplevel` returns the REAL path,
+  // but servedRoot may be reached through a symlink (macOS /tmp -> /private/var,
+  // or any symlinked served path). A raw path.resolve comparison false-negatives
+  // "same dir" and the code would wrongly try to git-sync the checkout onto
+  // itself. realPathOr fixes it. This test builds an EXPLICIT symlink so it holds
+  // on any OS (it FAILS against the old path.resolve code, PASSES with realpath).
+  const linkDir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-served-link-'));
+  const link = path.join(linkDir, 'served');
+  fs.symlinkSync(fs.realpathSync(tmp), link, 'dir');
+  try {
+    const r = sbx.syncWorktreeToServed({ cwd: tmp, servedRoot: link });
+    assert.equal(r.ok, true);
+    assert.equal(r.synced, false, 'a symlinked served root pointing at the session checkout must be recognized as the same dir, not synced as stale');
+  } finally {
+    fs.rmSync(linkDir, { recursive: true, force: true });
+  }
+});
+
+t('syncWorktreeToServed: detached HEAD / unresolvable branch → not ok', () => {
+  // execFileSync stub: toplevel resolves, but rev-parse --abbrev-ref returns HEAD
+  const stub = (cmd, args) => {
+    if (args.includes('--show-toplevel')) return '/some/worktree\n';
+    if (args.includes('--abbrev-ref')) return 'HEAD\n';
+    return '';
+  };
+  const r = sbx.syncWorktreeToServed({ execFileSync: stub, servedRoot: '/served' });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /could not resolve the session branch/);
+});
+
+await ta('verifyServedFresh: served bytes match worktree → ok/verified', async () => {
+  // dirty a tracked game file so pickVerifyTarget selects it
+  fs.writeFileSync(path.join(tmp, 'public', 'game.js'), 'served-match\n');
+  const r = await sbx.verifyServedFresh({
+    cwd: tmp,
+    healthUrl: 'http://127.0.0.1:3000/',
+    fetchImpl: async (url) => { assert.match(url, /\/game\.js$/); return { status: 200, text: async () => 'served-match\n' }; },
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.verified, 'public/game.js');
+  execFileSync('git', ['checkout', '--', 'public/game.js'], { cwd: tmp });
+});
+
+await ta('verifyServedFresh: served bytes DIFFER → not ok (serving stale code)', async () => {
+  fs.writeFileSync(path.join(tmp, 'public', 'game.js'), 'worktree-new\n');
+  const r = await sbx.verifyServedFresh({
+    cwd: tmp,
+    fetchImpl: async () => ({ status: 200, text: async () => 'stale-old\n' }),
+  });
+  assert.equal(r.ok, false);
+  assert.match(r.reason, /serving stale code/);
+  execFileSync('git', ['checkout', '--', 'public/game.js'], { cwd: tmp });
+});
+
+await ta('verifyServedFresh: no served static change → skipped (ok)', async () => {
+  // clean tree, no origin/main ref in the temp repo → pickVerifyTarget null
+  const r = await sbx.verifyServedFresh({ cwd: tmp, fetchImpl: async () => { throw new Error('must not fetch'); } });
+  assert.equal(r.ok, true);
+  assert.equal(r.skipped, true);
+});
+
+await ta('stage(box): a HARD sync failure → {ok:false,hard:true}, no marker; runShipGate ABORTS', async () => {
+  const mp = path.join(markerDir, 'hard1.json');
+  const deps = boxDeps(mp, { syncWorktreeToServed: () => ({ ok: false, reason: 'checkout failed' }) });
+  const staged = await sbx.stage({ taskId: 1068 }, deps);
+  assert.equal(staged.ok, false);
+  assert.equal(staged.hard, true);
+  assert.equal(fs.existsSync(mp), false, 'no marker on a hard sync failure');
+  // and the gate turns a hard failure into a claim-preserving abort
+  const r = await sbx.runShipGate({ taskId: 1068, files: ['public/game/a.js'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.review, true);
+  assert.match(r.reason, /could not be trusted/);
+});
+
+await ta('stage(box): a HARD verify failure → {ok:false,hard:true}, no marker', async () => {
+  const mp = path.join(markerDir, 'hard2.json');
+  const deps = boxDeps(mp, { verifyServedFresh: async () => ({ ok: false, reason: 'served stale' }) });
+  const staged = await sbx.stage({ taskId: 1068 }, deps);
+  assert.equal(staged.ok, false);
+  assert.equal(staged.hard, true);
+  assert.equal(fs.existsSync(mp), false, 'no marker on a hard verify failure');
+});
+
+await ta('runShipGate(box): a SOFT failure (preview never healthy) still warns + continues', async () => {
+  const mp = path.join(markerDir, 'soft1.json');
+  // sync ok (injected), but health never green → soft failure → ship continues
+  const deps = boxDeps(mp, { fetchImpl: async () => ({ status: 502 }), timeoutMs: 10 });
+  const r = await sbx.runShipGate({ taskId: 1068, files: ['public/game/a.js'], skipStage: false, tty: true }, deps);
+  assert.equal(r.ok, true, 'a broken preview must not brick shipping (soft failure)');
+});
+
+// ---------- runShipGate: LOCAL preview context + recorded approval (task 1056) ----------
+// A full local clone (laptop) gets the SAME enforced gate + recorded-approval as
+// a box (#1048), but staged at http://localhost:<port>. Inject the local context
+// directly so there is NO real spawn / network: restart is a no-op, health
+// answers 200, git is real on the temp repo, marker lives in the temp dir.
+function localDeps(markerFile, overrides = {}) {
+  return {
+    previewContext: {
+      kind: 'local',
+      url: 'http://localhost:3100',
+      healthUrl: 'http://127.0.0.1:3100/healthz',
+      restart: () => { /* pretend the local preview (re)started */ },
+    },
+    fs: {
+      existsSync: (p) => fs.existsSync(p),
+      readFileSync: (p, enc) => fs.readFileSync(p, enc),
+      writeFileSync: (p, d) => fs.writeFileSync(p, d),
+    },
+    execFileSync: (cmd, args, opts) => (cmd === 'git' ? execFileSync(cmd, args, opts) : ''),
+    fetchImpl: async () => ({ status: 200 }),
+    markerPath: markerFile,
+    cwd: tmp,
+    pollMs: 1,
+    timeoutMs: 1000,
+    ...overrides,
+  };
+}
+
+await ta('runShipGate(local): game diff + non-TTY → stages then ABORTS with the localhost URL', async () => {
+  const mp = path.join(markerDir, 'lm1.json');
+  const r = await sbx.runShipGate({ taskId: 1056, files: ['public/game/a.js'], skipStage: false, tty: false }, localDeps(mp));
+  assert.equal(r.ok, false, 'unreviewed game work must not ship non-interactively on a laptop');
+  assert.equal(r.review, true);
+  assert.match(r.reason, /staged at http:\/\/localhost:3100/i);
+  assert.ok(fs.existsSync(mp), 'work is staged so the human can review at localhost');
+});
+
+await ta('runShipGate(local): TTY yes → records a tty sign-off with the localhost URL + kind=local marker', async () => {
+  const mp = path.join(markerDir, 'lm2.json');
+  const r = await sbx.runShipGate({ taskId: 1056, files: ['src/world/terrain.js'], skipStage: false, tty: true }, localDeps(mp, { promptYesNo: async () => true }));
+  assert.equal(r.ok, true);
+  assert.equal(r.sandboxReview.method, 'tty');
+  assert.equal(r.sandboxReview.url, 'http://localhost:3100');
+  assert.ok(r.sandboxReview.stamp);
+  const m = JSON.parse(fs.readFileSync(mp, 'utf8'));
+  assert.equal(m.url, 'http://localhost:3100');
+  assert.equal(m.kind, 'local');
+});
+
+await ta('runShipGate(local): --approved re-run on a fresh stage records a flag sign-off', async () => {
+  const mp = path.join(markerDir, 'lm3.json');
+  const deps = localDeps(mp, { promptYesNo: async () => { throw new Error('must not prompt'); } });
+  sbx.writeMarker({ stamp: sbx.computeTreeStamp({ cwd: tmp }), url: 'http://localhost:3100' }, deps);
+  const r = await sbx.runShipGate({ taskId: 1056, files: ['server.js'], skipStage: false, tty: false, approved: true }, deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.sandboxReview.method, 'flag');
+  assert.equal(r.sandboxReview.url, 'http://localhost:3100');
+});
+
+await ta('runShipGate(local): non-game diff (clean tree) → skip, no staging', async () => {
+  const mp = path.join(markerDir, 'lm4.json');
+  const r = await sbx.runShipGate({ taskId: 1056, files: ['docs/x.md'], skipStage: false, tty: true }, localDeps(mp));
+  assert.equal(r.ok, true);
+  assert.equal(fs.existsSync(mp), false, 'no marker — nothing previewable');
+});
+
+fs.rmSync(tmp, { recursive: true, force: true });
+
+console.log(`\nsandbox_stage: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);