@bongos/core 1.19.711 → 1.19.712

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.711",
-  "core_contract": "1.19.711",
-  "source_commit": "51bef34ef27a7d94e516e2b1d10623eeebaf80a4",
+  "core_version": "1.19.712",
+  "core_contract": "1.19.712",
+  "source_commit": "e848d50ff42905384b1e3df672f2dfd3f6cebb23",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T07:20:01.517Z",
+  "built_at": "2026-09-13T07:31:19.809Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 478,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2649,
-  "tree_sha256": "15e6f8276b441266c13fefe89f515bf01b563021cd0be63afe1d36a9cc21ee5c",
+  "tree_sha256": "19c186cbca6bdf1dd7a73d69676cf9f52d37a5bd1dc25ed9eae3a46bdec158d2",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2807,7 +2807,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "aaf80c762f49609d71b0aafa23ac9b278a869d2f76e3b3901fee41d65956dd70"
+      "sha256": "90cfe161bdbb28b563fe34f367c2e5700149f07e2cec5f783f5db8bb9ea4b3db"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7817,12 +7817,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "048c83c4d1ec0e681d20c4c8da8b65a96e17ddbf88042082e109a0b0fd52e287"
+      "sha256": "0cdb4130832c4680860dc1687b17e496d4e3a6ff963898690d8b7301c4040835"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "098001e183920a73e0417d67b50b869c8d381a6d76ef884933d6872fb66e063d"
+      "sha256": "3c89b0fe35a5787a494119123aa0ba2a6e55f2428dfd912a208762e21743b71d"
     },
     {
       "path": "public-docs/index.html",
@@ -8762,7 +8762,7 @@
     {
       "path": "scripts/gds/sandbox-stage.js",
       "mode": "0000644",
-      "sha256": "583373b1d72c0a98aaafa0b57ecfcb1011fa2df9109fe312fb2f1c70234ae0d8"
+      "sha256": "9d7911da631e8da6c72875a6385502f4dfc0d2d6160ed95d56aa3f25c3f86878"
     },
     {
       "path": "scripts/gds/search-ingest-db.js",
@@ -9602,7 +9602,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "f53e83493d825804b8b4813d3c22b649d640757d6d10ec5e0d7fd70101510a2a"
+      "sha256": "aa71f9f73709ca7b062e9bb5994bfb2fa7d586aa3cca4e89daa74a3204a0db15"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12072,7 +12072,7 @@
     {
       "path": "tests/profile_route.mjs",
       "mode": "0000644",
-      "sha256": "ab6881bf65742f82dcb748daa5b8665c3a852a8fcc5aedb0a7040cafd6a3bdf4"
+      "sha256": "ef2a58d60f561da1e025cf0958bdcb66072545158a68f3e41b4bc683afbed9d6"
     },
     {
       "path": "tests/profile_ui_cross_project.mjs",
@@ -12492,7 +12492,7 @@
     {
       "path": "tests/sandbox_stage.mjs",
       "mode": "0000644",
-      "sha256": "9942d11ee2f72c23c648961d15e49375e5b030e2346f49050bef7238ca369109"
+      "sha256": "3873f8b93e78f026dd0dd6d8cdaf3aa68e73b3f9ce95d47bf8415cf242d42471"
     },
     {
       "path": "tests/scouting_owner_access_and_reach.mjs",

package/docs/module-api-changelog.md

@@ -1881,5 +1881,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.709 with no explicit bump. run 34744369035. (task 1002620)
   1.19.711 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.710 with no explicit bump. run 34744940181. (task 1002620)
+  1.19.712 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.711 with no explicit bump. run 34745412403. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.711",
+  "version": "1.19.712",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.711",
+      "version": "1.19.712",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.711",
+  "version": "1.19.712",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/sandbox-stage.js

@@ -44,10 +44,27 @@ const HEALTH_POLL_MS = 2_000;
 // 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'];
+// 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, and staging still reported
+// success because the two entrypoints below kept syncing — so a builder staged,
+// saw 'synced previewable surfaces', and got a sandbox serving whatever client
+// was already on /workspace (task 1002062; found when a new /studio page 404'd).
+const PREVIEWABLE_DIRS = ['modules/game/public', 'modules/game/world', 'modules/game/rooms'];
+// The single directory the preview serves AT THE URL ROOT: modules/game/public/x
+// is served as /x. pickVerifyTarget maps between the two, so it must be exactly
+// one dir — hence its own constant rather than PREVIEWABLE_DIRS[0].
+const PREVIEWABLE_STATIC_DIR = 'modules/game/public';
+// The entrypoints that render the game. A sparse box (STARTER_SPARSE_PATHS) may
+// legitimately lack these, which is why a miss here is not on its own an error.
+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];
 
 // 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
@@ -316,6 +333,11 @@ function syncWorktreeToServed(deps = {}) {
   // then overlay the session branch's content.
   let synced = false;
   let lastErr = null;
+  // task 1002062: this collapsed to a single boolean, so a run that synced ONLY
+  // the entrypoints and missed every client directory reported plain success.
+  // Track them by name — the caller warns on a missed DIRECTORY, which is the
+  // shape a stale pathspec list takes.
+  const missed = [];
   for (const ps of PREVIEWABLE_PATHSPECS) {
     try {
       run('git', ['-C', servedRoot, 'checkout', '--', ps], { stdio: 'ignore' });
@@ -327,12 +349,16 @@ function syncWorktreeToServed(deps = {}) {
       synced = true;
     } catch (e) {
       lastErr = e; // pathspec absent in the branch (sparse/missing) — skip it
+      missed.push(ps);
     }
   }
   if (!synced) {
-    return { ok: false, synced: false, reason: `git checkout ${branch} -- <previewable> in ${servedRoot} synced nothing${lastErr ? ` (${lastErr.message})` : ''}` };
+    return { ok: false, synced: false, missed, reason: `git checkout ${branch} -- <previewable> in ${servedRoot} synced nothing${lastErr ? ` (${lastErr.message})` : ''}` };
   }
-  return { ok: true, synced: true, branch };
+  // A missed ENTRYPOINT is normal on a sparse box. A missed client DIRECTORY means
+  // the sandbox is about to serve a client this stage never touched.
+  const missedDirs = missed.filter((m) => PREVIEWABLE_DIRS.includes(m));
+  return { ok: true, synced: true, branch, missed, missedDirs };
 }
 
 // Pick the smallest cheap-to-compare changed previewable static file to verify,
@@ -343,21 +369,26 @@ function pickVerifyTarget(deps = {}) {
   const cwd = deps.cwd || process.cwd();
   const f = deps.fs || fs;
   try {
-    const out = run('git', ['status', '--porcelain', '--', 'public'], { cwd, encoding: 'utf8' });
+    // task 1002062: this hardcoded 'public' three times, independently of the
+    // constants above, so it kept the pre-carve spelling even after they moved.
+    // Derived from PREVIEWABLE_STATIC_DIR now, so there is one place to change.
+    const staticDir = deps.staticDir || PREVIEWABLE_STATIC_DIR;
+    const prefix = `${staticDir}/`;
+    const out = run('git', ['status', '--porcelain', '--', staticDir], { 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)));
+      .find((rel) => rel && rel.startsWith(prefix) && 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' });
+      const diff = run('git', ['diff', '--name-only', 'origin/main...HEAD', '--', staticDir], { cwd, encoding: 'utf8' });
       chosen = diff
         .split('\n')
         .map((s) => s.trim())
-        .find((p) => p.startsWith('public/') && f.existsSync(path.join(cwd, p)));
+        .find((p) => p.startsWith(prefix) && f.existsSync(path.join(cwd, p)));
     }
     if (!chosen) return null;
-    return { relPath: chosen, urlPath: '/' + chosen.replace(/^public\//, '') };
+    return { relPath: chosen, urlPath: '/' + chosen.slice(prefix.length) };
   } catch {
     return null;
   }
@@ -374,7 +405,7 @@ async function verifyServedFresh(deps = {}) {
   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)' };
+  if (!target) return { ok: true, skipped: true, reason: `no served static change to verify (e.g. only ${PREVIEWABLE_DIRS.filter((d) => d !== PREVIEWABLE_STATIC_DIR).join(' or ')} changed)` };
   let want;
   try {
     want = f.readFileSync(path.join(cwd, target.relPath), 'utf8');
@@ -455,6 +486,16 @@ async function stage({ taskId } = {}, deps = {}) {
       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}`);
+    // task 1002062 — the tell that went unsaid for 69 days. Staging "succeeded"
+    // while every game-client directory matched nothing, so the sandbox served a
+    // client the stage never touched and the only hint was a freshness-verify skip.
+    if (sync.missedDirs && sync.missedDirs.length) {
+      console.warn(
+        `  ⚠ these previewable directories matched NOTHING in ${sync.branch}: ${sync.missedDirs.join(', ')}`
+        + ' — the sandbox will serve whatever client is already on the served checkout.'
+        + ' If this repo carved or renamed them, PREVIEWABLE_DIRS in sandbox-stage.js is stale.'
+      );
+    }
   }
   try {
     ctx.restart(deps);
@@ -699,6 +740,9 @@ module.exports = {
   BOX_ENV_PATH,
   BOX_SERVED_ROOT,
   PREVIEWABLE_PATHSPECS,
+  PREVIEWABLE_DIRS,
+  PREVIEWABLE_ENTRYPOINTS,
+  PREVIEWABLE_STATIC_DIR,
   sessionCheckoutRoot,
   syncWorktreeToServed,
   pickVerifyTarget,

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.711'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.712'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/profile_route.mjs

@@ -157,7 +157,6 @@ require.cache[authPath] = {
   id: authPath, filename: authPath, loaded: true,
   exports: {
     requireBuilder: (_req, _res, next) => next(),
-    requireRank: () => (_req, _res, next) => next(),
     requirePermission: () => (_req, _res, next) => next(),
     // ADR 0215 D4: the sliver route beside the directory gates on RANK, so the
     // partial doorway must answer requireRank too or the router will not load.

package/tests/sandbox_stage.mjs

@@ -57,7 +57,7 @@ t('previewUrl: reads box.env via injected fs; null when unreadable', () => {
 
 // ---------- 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']) {
+  for (const f of ['modules/game/public/game/main.js', 'modules/game/world/terrain.js', 'modules/game/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']) {
@@ -66,7 +66,7 @@ t('isPreviewableFile: game surfaces yes, internal surfaces no', () => {
 });
 
 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', 'modules/game/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);
@@ -162,9 +162,9 @@ 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, 'modules', 'game', 'public'), { recursive: true });
 fs.mkdirSync(path.join(tmp, 'docs'));
-fs.writeFileSync(path.join(tmp, 'public', 'game.js'), 'one\n');
+fs.writeFileSync(path.join(tmp, 'modules', 'game', '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', '.');
@@ -181,7 +181,7 @@ t('computeTreeStamp: content-stable, scoped to game surfaces', () => {
   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');
+  fs.writeFileSync(path.join(tmp, 'modules', 'game', 'public', 'game.js'), 'two\n');
   const s3 = sbx.computeTreeStamp({ cwd: tmp });
   assert.notEqual(s3, s1, 'game edit → new stamp');
 
@@ -192,10 +192,10 @@ t('computeTreeStamp: content-stable, scoped to game surfaces', () => {
   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');
+  fs.writeFileSync(path.join(tmp, 'modules', 'game', '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'));
+  fs.rmSync(path.join(tmp, 'modules', 'game', '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');
@@ -265,7 +265,7 @@ await ta('runShipGate: no sandbox available (not a box, no local game entry) →
   // 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 },
+    { taskId: 1, files: ['modules/game/public/game/a.js'], skipStage: false, tty: true },
     { fs: { existsSync: () => false } }
   );
   assert.equal(r.ok, true);
@@ -281,7 +281,7 @@ await ta('runShipGate: box + non-game diff → ok, no staging', async () => {
 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);
+  const r = await sbx.runShipGate({ taskId: 927, files: ['modules/game/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');
@@ -295,7 +295,7 @@ await ta('runShipGate: box + game diff + TTY, reviewer says yes → stages then
 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);
+  const r = await sbx.runShipGate({ taskId: 927, files: ['modules/game/public/game/a.js'], skipStage: false, tty: true }, deps);
   assert.equal(r.ok, false);
   assert.match(r.reason, /sandbox review declined/);
 });
@@ -321,14 +321,14 @@ await ta('runShipGate: stale marker forces a re-stage (stamp mismatch)', async (
 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);
+  const r = await sbx.runShipGate({ taskId: 927, files: ['modules/game/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);
+  const r2 = await sbx.runShipGate({ taskId: 927, files: ['modules/game/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');
 });
@@ -336,16 +336,16 @@ await ta('runShipGate: non-TTY → stages then ABORTS with the review URL (no pr
 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');
+  fs.writeFileSync(path.join(tmp, 'modules', 'game', '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');
+  git('checkout', '--', 'modules/game/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));
+  const r = await sbx.runShipGate({ taskId: 927, files: ['modules/game/public/game/a.js'], skipStage: true, tty: true }, boxDeps(mp));
   assert.equal(r.ok, true);
   assert.equal(fs.existsSync(mp), false);
 });
@@ -357,7 +357,7 @@ await ta('runShipGate: --skip-stage → ok, untouched', async () => {
 await ta('1002607 runShipGate: staging failure (health never green) ABORTS — review gate cannot silently turn itself off', 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);
+  const r = await sbx.runShipGate({ taskId: 927, files: ['modules/game/public/game/a.js'], skipStage: false, tty: true }, deps);
   assert.equal(r.ok, false, 'a failed stage must not ship as if the review happened');
   assert.equal(r.review, undefined, 'a failure to present is NOT a calm review pause');
   assert.match(r.reason, /DID NOT run/, 'says plainly the review step did not run');
@@ -384,7 +384,7 @@ await ta('runShipGate: --approved cannot pre-approve an UNstaged change (still s
   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);
+  const r = await sbx.runShipGate({ taskId: 1048, files: ['modules/game/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');
@@ -402,13 +402,13 @@ await ta('syncWorktreeToServed: brings the branch content into the served checko
   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');
+  fs.mkdirSync(path.join(served, 'modules', 'game', 'public'), { recursive: true });
+  fs.writeFileSync(path.join(served, 'modules', 'game', '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');
+  fs.writeFileSync(path.join(wt, 'modules', 'game', 'public', 'game.js'), 'BRANCH content\n');
   execFileSync('git', ['add', '.'], { cwd: wt });
   execFileSync('git', ['commit', '-qm', 'branch edit'], { cwd: wt });
 
@@ -419,7 +419,7 @@ await ta('syncWorktreeToServed: brings the branch content into the served checko
   // The claim is WHICH content landed, not how its lines end: git checks the fixture
   // out under the machine's own autocrlf, so on Windows the file comes back CRLF and a
   // byte-exact compare failed for a reason unrelated to the sync (task 1003529).
-  assert.ok(sameContent(fs.readFileSync(path.join(served, 'public', 'game.js'), 'utf8'), 'BRANCH content\n'),
+  assert.ok(sameContent(fs.readFileSync(path.join(served, 'modules', 'game', 'public', 'game.js'), 'utf8'), 'BRANCH content\n'),
     'served /workspace now shows the SESSION branch content, not stale main');
 
   g('worktree', 'remove', '--force', wt);
@@ -469,26 +469,26 @@ t('syncWorktreeToServed: detached HEAD / unresolvable branch → not ok', () =>
 
 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');
+  fs.writeFileSync(path.join(tmp, 'modules', 'game', '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 });
+  assert.equal(r.verified, 'modules/game/public/game.js');
+  execFileSync('git', ['checkout', '--', 'modules/game/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');
+  fs.writeFileSync(path.join(tmp, 'modules', 'game', '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 });
+  execFileSync('git', ['checkout', '--', 'modules/game/public/game.js'], { cwd: tmp });
 });
 
 await ta('verifyServedFresh: no served static change → skipped (ok)', async () => {
@@ -506,7 +506,7 @@ await ta('stage(box): a HARD sync failure → {ok:false,hard:true}, no marker; r
   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);
+  const r = await sbx.runShipGate({ taskId: 1068, files: ['modules/game/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/);
@@ -526,7 +526,7 @@ await ta('1002607 runShipGate(box): a SOFT failure (preview never healthy) now f
   // sync ok (injected), but health never green → the ship must NOT continue
   // as if the review ran (that was the silent-disable defect).
   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);
+  const r = await sbx.runShipGate({ taskId: 1068, files: ['modules/game/public/game/a.js'], skipStage: false, tty: true }, deps);
   assert.equal(r.ok, false, 'the soft failure aborts instead of silently skipping the review');
   assert.match(r.reason, /sandbox staging failed/);
 });
@@ -610,7 +610,7 @@ function localDeps(markerFile, 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));
+  const r = await sbx.runShipGate({ taskId: 1056, files: ['modules/game/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);
@@ -619,7 +619,7 @@ await ta('runShipGate(local): game diff + non-TTY → stages then ABORTS with th
 
 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 }));
+  const r = await sbx.runShipGate({ taskId: 1056, files: ['modules/game/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');
@@ -648,5 +648,86 @@ await ta('runShipGate(local): non-game diff (clean tree) → skip, no staging',
 
 fs.rmSync(tmp, { recursive: true, force: true });
 
+// ---------- 1002062: the surface list must describe a REAL tree ----------
+//
+// WHY THESE EXIST. Every case above feeds sandbox-stage its own fixture paths,
+// so the previewable list matched NOTHING in the real repo for 69 days and all
+// 47 tests stayed green. A suite that supplies the paths it tests cannot notice
+// that the paths are wrong. These four look at the real thing instead.
+
+t('1002062 the three surface spellings are DERIVED, so they cannot drift apart', () => {
+  // They used to be three hand-maintained copies. The module carve updated none
+  // of them, and nothing compared them. Derivation is the fix; this pins it.
+  assert.deepEqual(
+    sbx.PREVIEWABLE_PATHSPECS,
+    [...sbx.PREVIEWABLE_DIRS, ...sbx.PREVIEWABLE_ENTRYPOINTS],
+    "PATHSPECS must be derived from DIRS + ENTRYPOINTS, not hand-listed"
+  );
+  for (const d of sbx.PREVIEWABLE_DIRS) {
+    assert.equal(sbx.isPreviewableFile(`${d}/some/file.js`), true, `${d} must match via the derived prefixes`);
+  }
+  for (const e of sbx.PREVIEWABLE_ENTRYPOINTS) {
+    assert.equal(sbx.isPreviewableFile(e), true, `${e} must match via the derived file set`);
+  }
+});
+
+t('1002062 no PRE-CARVE relic survives in the surface list', () => {
+  // The exact spellings that were stale: the carve (ADR 0083 / task 1418) moved
+  // them under modules/game/ and this list kept the old ones.
+  for (const relic of ['public', 'src/world', 'src/rooms']) {
+    assert.ok(
+      !sbx.PREVIEWABLE_PATHSPECS.includes(relic),
+      `${relic} is the pre-carve spelling and matches nothing — it must not be back`
+    );
+  }
+  assert.ok(sbx.PREVIEWABLE_STATIC_DIR.startsWith('modules/'), 'the served static dir is module-carved');
+});
+
+t('1002062 a client directory that matched NOTHING is reported, not swallowed', () => {
+  // THE ACTUAL BUG. The sync collapsed to one boolean, so a run that synced only
+  // the entrypoints and missed every client dir reported plain success — the
+  // reporter saw "synced previewable surfaces" and got a stale sandbox.
+  const served = fs.mkdtempSync(path.join(os.tmpdir(), "sbx-missed-"));
+  const session = fs.mkdtempSync(path.join(os.tmpdir(), "sbx-sess-"));
+  const calls = [];
+  const execFileSyncStub = (bin, args) => {
+    const a = args.join(" ");
+    if (a.includes("rev-parse")) return "feature-branch\n";
+    // Entrypoints resolve; every client directory is absent from the branch.
+    const ps = args[args.length - 1];
+    if (sbx.PREVIEWABLE_DIRS.includes(ps) && a.includes("feature-branch")) {
+      throw new Error(`pathspec ${ps} did not match any file(s) known to git`);
+    }
+    calls.push(a);
+    return "";
+  };
+  const r = sbx.syncWorktreeToServed({
+    execFileSync: execFileSyncStub,
+    servedRoot: served,
+    sessionRoot: session,
+    cwd: session,
+  });
+  assert.equal(r.ok, true, "the entrypoints synced, so the sync itself is not a hard failure");
+  assert.deepEqual(
+    r.missedDirs, sbx.PREVIEWABLE_DIRS,
+    "every client directory missed, and the caller must be told which"
+  );
+});
+
+t('1002062 pickVerifyTarget maps the CARVED static dir onto the served URL', () => {
+  // modules/game/public/game.js is served at /game.js. The old code stripped a
+  // hardcoded "public/" prefix, which post-carve would have left the whole
+  // modules/game/ path in the URL.
+  const rel = `${sbx.PREVIEWABLE_STATIC_DIR}/game.js`;
+  const target = sbx.pickVerifyTarget({
+    cwd: "/nowhere",
+    fs: { existsSync: () => true },
+    execFileSync: (bin, args) => (args.includes("--porcelain") ? ` M ${rel}\n` : ""),
+  });
+  assert.ok(target, "a changed file under the static dir must be pickable");
+  assert.equal(target.relPath, rel);
+  assert.equal(target.urlPath, "/game.js", "the carved prefix is stripped, not just \"public/\"");
+});
+
 console.log(`\nsandbox_stage: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);