@bongos/core 1.19.1081 → 1.20.1

package/tests/ideator_full_idea_shapes_space_proof.mjs

@@ -148,7 +148,7 @@ function answer(sql, params) {
       description: description ?? null, scope_modules: scopeModules || [], status,
       visibility: 'public', accepting_requests: true, created_by: createdBy ?? null,
       succeeded_by_goal_id: null, sort_order: order, category_id: categoryId ?? null,
-      is_maintenance: false, created_at: 'T1', updated_at: 'T1',
+      is_maintenance: false, working_area: null, created_at: 'T1', updated_at: 'T1',
     };
     db.goals.set(goal.id, goal);
     // The two CTE side-writes, modelled because they are what makes `created_by`

package/tests/landing_page.mjs

@@ -564,14 +564,17 @@ test('the Projects band deep-links the hub\'s views; About and Docs are footer l
   assert.match(body, /<a href="#about">About<\/a>\s*<a href="\/docs">Docs<\/a>\s*<a href="\/privacy">Privacy<\/a>/, 'About and Docs open the footer row');
   assert.match(body, /<section class="band" id="about">/, 'About has a real anchor: the lifecycle band');
   assert.doesNotMatch(body.split('<main')[0], /aria-current/, 'the landing is none of those views');
-  // the profile band: the person, My projects, the deferred slot, Sign out as the honest anchor
+  // the profile band: the person, My projects, Account, Sign out as the honest anchor.
+  // Account fills the slot that waited for a settings page (task 1004259) and is
+  // apex-only, because /account is served only where platform-identity runs.
   assert.match(body, /<div class="menuBand" id="menuProfile" data-menu="profile" hidden>/);
   assert.match(body, /<p class="bandWho" id="bandWho"><\/p>/);
   assert.match(body, /<a class="bandT" href="\/projects\?view=mine">My projects<\/a>/);
-  assert.match(body, /<li class="bandSlot" aria-hidden="true"><\/li>/);
+  assert.match(body, /<!--apex-only:start--><li class="bandCell"><a class="bandT" href="\/account">Account<\/a><\/li><!--apex-only:end-->/);
+  assert.doesNotMatch(body, /class="bandSlot"/, 'the slot is filled, not kept beside its item');
   assert.match(body, /<a class="bandT signout" href="\/api\/bongos\/auth\/logout">Sign out<\/a>/);
   // a crawler reads every destination without scripting on
-  for (const copy of ['Sky', 'Table', 'Your projects', 'New project', 'About', 'Docs', 'My projects', 'Sign out']) {
+  for (const copy of ['Sky', 'Table', 'Your projects', 'New project', 'About', 'Docs', 'My projects', 'Account', 'Sign out']) {
     assert.ok(body.includes('>' + copy + '<'), `"${copy}" is only reachable with scripting on`);
   }
   // the menu container is .menuBand: .band is this page's own content sections

package/tests/module-scope-map.mjs

@@ -591,14 +591,11 @@ function ownersOf(p) {
   return scope.moduleKeys().filter((k) => matchOne(p, scope.scopeForModule(k).globs) !== null);
 }
 
-// The one PROTECTED_GLOBS entry still owned by nobody, exempted BY NAME so the
-// tripwire stays true rather than being weakened to accommodate it.
-// src/bongos/routes/ is a blanket directory: protection covers all 18 files under
-// it, authoring covers 2 (me.js -> builder-settings, security.js -> kernel).
-// Closing it means deciding who owns the other sixteen live route files, which is
-// an ownership call and not a missing glob — filed as task 1004116. Removing this
-// entry is that task's first step.
-const UNOWNED_EXEMPT = ['src/bongos/routes/'];
+// PROTECTED_GLOBS entries still owned by nobody, exempted BY NAME so the
+// tripwire stays true rather than being weakened to accommodate one. EMPTY since
+// task 1004116 gave src/bongos/routes/ to kernel; keep it empty — a new entry
+// here is a new hole, and the test below refuses one that has stopped applying.
+const UNOWNED_EXEMPT = [];
 
 test('every PROTECTED_GLOBS entry is owned by at least one module', () => {
   const unowned = PROTECTED_GLOBS
@@ -610,6 +607,32 @@ test('every PROTECTED_GLOBS entry is owned by at least one module', () => {
   );
 });
 
+// task 1004116: the entry-level tripwire above passes on a blanket DIRECTORY as
+// soon as some module owns the directory — but it said nothing about the FILES
+// inside one, which is exactly how sixteen route files sat under a protected
+// prefix that no goal could author. So walk every file under every blanket
+// (trailing-'/') protected glob and ask the wall's own question of each: does
+// some module's territory cover THIS path? matchOne takes an ARRAY (the probe
+// trap pinned below).
+test('every FILE under a blanket protected directory has an owning module (task 1004116)', () => {
+  const walk = (rel) => {
+    const abs = path.join(ROOT, rel);
+    if (!fs.existsSync(abs)) return [];
+    return fs.readdirSync(abs, { withFileTypes: true }).flatMap((d) =>
+      d.isDirectory() ? walk(rel + d.name + '/') : [rel + d.name]);
+  };
+  const blankets = PROTECTED_GLOBS.filter((g) => g.endsWith('/'));
+  const files = blankets.flatMap(walk);
+  assert.ok(files.length > 0, 'no files found under any blanket protected glob — the walk is broken, not clean');
+  assert.ok(files.includes('src/bongos/routes/public.js'), 'the walk must reach the route directory');
+  const unowned = files.filter((p) => ownersOf(p).length === 0);
+  assert.deepEqual(unowned, [], 'these protected files are authorable by NO goal');
+  for (const f of ['audit-log.js', 'auth.js', 'core-update.js', 'public.js', '_helpers.js', 'CLAUDE.md']) {
+    const p = 'src/bongos/routes/' + f;
+    assert.equal(gsc.scopeSubset(['kernel'], [p]).ok, true, p + ' must be authorable by a kernel-scoped goal');
+  }
+});
+
 test('the exemption list is not a place to hide a new hole', () => {
   // An exemption that silently stops applying is worse than none: it would sit
   // in the file implying a known gap that no longer exists, and the next unowned

package/tests/module_api.mjs

@@ -35,6 +35,7 @@ const PUBLISHED_SURFACE = [
   'routeRankCheck', 'permissionPathCheck', // BV1.R73: kernel trust classifiers (1.6.0)
   'repoInfo', 'moduleScopeMap', 'pathMatch', // BV1.R86: kernel repo-identity + scope-wall + touches-overlap for the carved lifecycle (1.12.0)
   'goalScopeCheck', // BV1.R60: kernel scope wall for the goal-authored-task create gate (1.13.0; ADR 0086 §3)
+  'cascadeDispatch', // task 1001691 / ADR 0101 Part 1: cheapest-model-first cascade router (1.20.0; the lifecycle relevance judge's first real caller)
   'insertAuditLog', 'LIVE_RANK_LADDER', // createTask + VOTABLE_TASK_STATUSES + tallyPeerVotes RETIRED at 1.12.0 (BV1.R86 → lifecycle port); captureIdea retired at 1.8.0 (BV1.R78 → ideas.capture port)
   'RANK_TIER', // BV1.R108: the canonical 1-based rank→tier map, derived from LIVE_RANK_LADDER (tests/rank_tier_single_source.mjs)
   'llmCache', // BV1.R73: shared LLM-cost cache (1.6.0; tracked domain leak)

package/tests/module_loader.mjs

@@ -276,7 +276,7 @@ test('the live tree discovers the extracted modules cleanly (BV1.R43/R48/R47/R49
   // That is precisely how the agents regression reached an open PR (task 1002485).
   loader._reset();
   const snap = loader.loaderSnapshot();
-  assert.deepEqual(snap.loaded, ['agents', 'autonomy', 'builder-settings', 'copy-desk', 'discord', 'economy', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'npm-release', 'onboarding', 'platform-identity', 'provisioning', 'public-landing', 'security', 'sessions', 'specialities', 'status-ui', 'ui-design']);
+  assert.deepEqual(snap.loaded, ['agents', 'autonomy', 'builder-settings', 'copy-desk', 'discord', 'economy', 'government', 'grading', 'hall-ui', 'ideas', 'lifecycle', 'memory', 'npm-release', 'onboarding', 'platform-identity', 'provisioning', 'public-landing', 'render-deploy', 'security', 'sessions', 'specialities', 'status-ui', 'ui-design']);
   assert.deepEqual(snap.errors, []);
   assert.deepEqual(snap.skipped, []);
   loader._reset();

package/tests/nav_permission_atoms.mjs

@@ -87,7 +87,7 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // the file and left the query alone, so a returning browser kept the cached copy —
 // a fix that reaches nobody looks identical to a fix that does not work.
 
-const SHELL_SHA = '0c646e5bac9336e8';
+const SHELL_SHA = 'dd33737d54dccbb4';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);

package/tests/no_phantom_mirror_workflow.mjs

@@ -0,0 +1,24 @@
+// tests/no_phantom_mirror_workflow.mjs — task 1003405.
+// No tracked file may point at a sync-public-mirror workflow that does not exist, unless it
+// says so plainly ("never built" / "no sync-public-mirror workflow"). Publishing the public
+// mirror is a manual step (node scripts/public-mirror-export.js ... --push).
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+if (!fs.existsSync(path.join(root, '.github/workflows/sync-public-mirror.yml'))) {
+  const files = execFileSync('git', ['ls-files'], { cwd: root, encoding: 'utf8', maxBuffer: 1 << 26 }).split('\n').filter(Boolean);
+  const bad = [];
+  for (const f of files) {
+    if (f === 'tests/no_phantom_mirror_workflow.mjs') continue;
+    const p = path.join(root, f);
+    if (!fs.existsSync(p) || fs.statSync(p).size > 2e6) continue;
+    const t = fs.readFileSync(p, 'utf8');
+    if (t.includes('sync-public-mirror') && !/never built|no sync-public-mirror workflow/.test(t)) bad.push(f);
+  }
+  assert.deepEqual(bad, [], 'these files reference a sync-public-mirror workflow that does not exist: ' + bad.join(', '));
+}
+console.log('ok - no phantom sync-public-mirror workflow reference');

package/tests/npm_release_preview_commands.mjs

@@ -0,0 +1,89 @@
+// tests/npm_release_preview_commands.mjs — the commands a preview start runs (task 1004300).
+//
+// WHAT IS AT RISK. Two things go wrong quietly here. (1) A template copy of the database
+// (createdb -T) needs the source to have no other connections; the live hall holds a pool
+// open, so it would fail, or evict the live pool. The copy must be a dump and a restore,
+// and NO command may ever carry -T / --template. (2) A version string that reaches a command
+// line unchecked. Commands are data, so both are asserted on the data, spawning nothing.
+//
+// Run:  node --test tests/npm_release_preview_commands.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const c = require('../modules/npm-release/preview/commands.js');
+const { PREVIEW_DB } = require('../modules/npm-release/preview/env.js');
+
+// Paths are compared with forward slashes so the file passes on a Windows checkout too.
+const fwd = (x) => String(x).split(String.fromCharCode(92)).join('/');
+const CACHE = '/home/hall/.cache/bongos-preview';
+const V = '1.19.1000';
+
+function everyCommand() {
+  return [
+    c.installCommand({ cacheRoot: CACHE, version: V }),
+    c.dropDbCommand(),
+    c.createDbCommand(),
+    c.dumpCommand({ liveDb: 'live_db', dumpFile: '/tmp/x.dump' }),
+    c.restoreCommand({ dumpFile: '/tmp/x.dump' }),
+    c.migrateCommand({ cacheRoot: CACHE, version: V, env: { PATH: '/bin' } }),
+  ];
+}
+
+test('no command ever copies the database from a template (-T / --template)', () => {
+  for (const cmd of everyCommand()) {
+    for (const a of cmd.args) {
+      assert.notEqual(a, '-T', `${cmd.cmd} carries -T`);
+      assert.doesNotMatch(a, /^--template/, `${cmd.cmd} carries --template`);
+    }
+    assert.doesNotMatch(cmd.args.join(' '), /(^|\s)-T(\s|$)/);
+  }
+});
+
+test('the copy is a custom-format dump of the live database, restored with no owner', () => {
+  const dump = c.dumpCommand({ liveDb: 'live_db', dumpFile: '/tmp/x.dump' });
+  assert.equal(dump.cmd, 'pg_dump');
+  assert.deepEqual(dump.args, ['-Fc', '-f', '/tmp/x.dump', 'live_db']);
+  const restore = c.restoreCommand({ dumpFile: '/tmp/x.dump' });
+  assert.equal(restore.cmd, 'pg_restore');
+  assert.deepEqual(restore.args, ['--no-owner', '-d', PREVIEW_DB, '/tmp/x.dump']);
+});
+
+test('the copy is created empty and dropped if it is already there', () => {
+  assert.deepEqual(c.createDbCommand(), { cmd: 'createdb', args: [PREVIEW_DB] });
+  assert.deepEqual(c.dropDbCommand(), { cmd: 'dropdb', args: ['--if-exists', PREVIEW_DB] });
+});
+
+test('the install is one version of the core into its own directory, production dependencies only', () => {
+  const i = c.installCommand({ cacheRoot: CACHE, version: V });
+  assert.equal(i.cmd, 'npm');
+  assert.deepEqual(i.args.map(fwd), ['install', '--prefix', `${CACHE}/${V}`, `@bongos/core@${V}`, '--omit=dev']);
+});
+
+test('migrations run the installed version against the copy, with the live pool and URL out of reach', () => {
+  const m = c.migrateCommand({ cacheRoot: CACHE, version: V, env: { PATH: '/bin', PGDATABASE: 'live_db', DATABASE_URL: 'postgres://live' } });
+  assert.equal(m.cmd, 'bash');
+  assert.match(fwd(m.args[0]), new RegExp(`${V}/node_modules/@bongos/core/scripts/migrate\.sh$`));
+  assert.equal(fwd(m.env.INIT_CWD), `${CACHE}/${V}`);
+  assert.equal(m.env.PGDATABASE, PREVIEW_DB);
+  assert.equal(m.env.DATABASE_URL, '');
+  assert.equal(fwd(m.cwd), `${CACHE}/${V}`);
+});
+
+test('the preview process is the installed core server entry', () => {
+  assert.equal(fwd(c.entryPath(CACHE, V)), `${CACHE}/${V}/node_modules/@bongos/core/src/platform-server.js`);
+});
+
+test('a version that is not three plain numbers never reaches a command', () => {
+  for (const bad of ['1.19', '1.19.x', '1.19.1000; rm -rf /', '../../etc', '1.19.1000-beta', '', '$(id)', '1.19.1000\n']) {
+    assert.throws(() => c.installCommand({ cacheRoot: CACHE, version: bad }), /not a version/, JSON.stringify(bad));
+    assert.throws(() => c.migrateCommand({ cacheRoot: CACHE, version: bad, env: {} }), /not a version/);
+    assert.throws(() => c.entryPath(CACHE, bad), /not a version/);
+  }
+});
+
+test('the preview database can never be the source of its own copy', () => {
+  assert.throws(() => c.dumpCommand({ liveDb: PREVIEW_DB, dumpFile: '/tmp/x' }), /preview database itself/);
+  assert.throws(() => c.dumpCommand({ liveDb: '', dumpFile: '/tmp/x' }), /live database name/);
+});

package/tests/npm_release_preview_divert.mjs

@@ -0,0 +1,164 @@
+// tests/npm_release_preview_divert.mjs — which requests the version preview takes (task 1004300).
+//
+// WHAT IS AT RISK. The provider decides, on every request to the whole hall, whether the
+// live hall or a copy answers. Get it wrong one way and a person keeps working in a preview
+// they thought they had left, or a CLI call writes to a copy and is lost; the other way and
+// somebody without the deploy permission is shown production data through a preview. Every
+// rule is a case here, and the gates are the kernel's own shape (express-style, refusing
+// through res.fail), stubbed with no database.
+//
+// Run:  node --test tests/npm_release_preview_divert.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { createDivert, cookieVersion, clearCookie } = require('../modules/npm-release/preview/divert.js');
+
+const RUNNING = { state: 'running', version: '1.19.1000', port: 3190 };
+
+// A builder table the stub gates read: cookie sid -> { id, perms }.
+function rig({ status = RUNNING, builders = { good: { id: 7, perms: ['core.pin.move'] } }, throwIn } = {}) {
+  const out = { forwarded: 0, touched: 0, asked: [], gateRuns: 0 };
+  const supervisor = { status: () => status, touch: () => { out.touched += 1; } };
+  const requireBuilder = async (req, res, next) => {
+    out.gateRuns += 1;
+    if (throwIn === 'builder') throw new Error('db down');
+    const sid = /sid=(\w+)/.exec(req.headers.cookie || '');
+    const b = sid && builders[sid[1]];
+    if (!b) return res.fail('unauthenticated', 401);
+    req.builder = b;
+    return next();
+  };
+  const requirePermission = (...atoms) => {
+    out.asked.push(atoms);
+    return async (req, res, next) => {
+      if (throwIn === 'permission') throw new Error('resolver down');
+      return atoms.every((a) => req.builder.perms.includes(a)) ? next() : res.fail('permission_forbidden', 403);
+    };
+  };
+  const divert = createDivert({ supervisor, forward: () => { out.forwarded += 1; }, requireBuilder, requirePermission });
+  return { divert, out, builders };
+}
+
+function req(over = {}) {
+  return { originalUrl: '/builders', headers: { cookie: 'sid=good; bongos_preview=1.19.1000', ...(over.headers || {}) }, ...over };
+}
+
+async function run(divert, r) {
+  const set = [];
+  let passed = 0;
+  await divert(r, { append: (k, v) => set.push([k, v]) }, () => { passed += 1; });
+  return { passed, set };
+}
+
+test('the cookie is read only when it names a real version', () => {
+  assert.equal(cookieVersion('a=1; bongos_preview=1.19.1000'), '1.19.1000');
+  assert.equal(cookieVersion('bongos_preview=latest'), null);
+  assert.equal(cookieVersion('bongos_preview=1.19.1000x'), null);
+  assert.equal(cookieVersion(''), null);
+  assert.equal(cookieVersion(undefined), null);
+});
+
+test('a signed-in holder of core.pin.move with the cookie is forwarded, and the preview is kept alive', async () => {
+  const { divert, out } = rig();
+  const r = await run(divert, req());
+  assert.equal(out.forwarded, 1);
+  assert.equal(r.passed, 0);
+  assert.equal(out.touched, 1);
+});
+
+test('the permission asked for is exactly core.pin.move', () => {
+  const { out } = rig();
+  assert.deepEqual(out.asked, [['core.pin.move']]);
+});
+
+test('no cookie: straight through, and no gate is even run', async () => {
+  const { divert, out } = rig();
+  const r = await run(divert, req({ headers: { cookie: 'sid=good' } }));
+  assert.equal(r.passed, 1);
+  assert.equal(out.forwarded, 0);
+  assert.equal(out.gateRuns, 0);
+});
+
+test('forwarding is refused without the permission, and the cookie is cleared', async () => {
+  const { divert, out } = rig({ builders: { good: { id: 7, perms: ['some.other'] } } });
+  const r = await run(divert, req());
+  assert.equal(out.forwarded, 0);
+  assert.equal(r.passed, 1);
+  assert.deepEqual(r.set, [['Set-Cookie', clearCookie()]]);
+});
+
+test('forwarding is refused when nobody is signed in', async () => {
+  const { divert, out } = rig();
+  const r = await run(divert, req({ headers: { cookie: 'bongos_preview=1.19.1000' } }));
+  assert.equal(out.forwarded, 0);
+  assert.equal(r.passed, 1);
+});
+
+test('the permission is re-checked on every request: revoked between two clicks, the second is not forwarded', async () => {
+  const { divert, out, builders } = rig();
+  await run(divert, req());
+  assert.equal(out.forwarded, 1);
+  builders.good.perms = [];
+  const r = await run(divert, req());
+  assert.equal(out.forwarded, 1, 'still one');
+  assert.equal(r.passed, 1);
+});
+
+test('a gate that throws forwards nothing (fail closed)', async () => {
+  for (const throwIn of ['builder', 'permission']) {
+    const { divert, out } = rig({ throwIn });
+    const r = await run(divert, req());
+    assert.equal(out.forwarded, 0, throwIn);
+    assert.equal(r.passed, 1, throwIn);
+  }
+});
+
+test('sign-in is never forwarded: /api/bongos/auth/* and the /api/gds alias reach the live hall', async () => {
+  for (const url of ['/api/bongos/auth/web/start', '/api/bongos/auth/callback?code=1', '/api/gds/auth/web/start', '/api/bongos/auth', '/api/bongos/v1/auth/web/start', '/api/gds/v1/auth/web/start']) {
+    const { divert, out } = rig();
+    const r = await run(divert, req({ originalUrl: url }));
+    assert.equal(out.forwarded, 0, url);
+    assert.equal(r.passed, 1, url);
+  }
+});
+
+test('leaving a preview is never forwarded: the exit route (and every preview route) reaches the live hall', async () => {
+  for (const url of ['/api/bongos/npm-release/preview/exit', '/api/bongos/npm-release/preview', '/api/bongos/npm-release/preview/enter?v=1.19.1000', '/api/bongos/v1/npm-release/preview/exit', '/api/bongos/v1/npm-release/preview']) {
+    const { divert, out } = rig();
+    const r = await run(divert, req({ originalUrl: url }));
+    assert.equal(out.forwarded, 0, url);
+    assert.equal(r.passed, 1, url);
+  }
+});
+
+test('a look-alike path is still forwarded: only the exact prefixes are excluded', async () => {
+  for (const url of ['/api/bongos/npm-release/previews', '/api/bongos/authors', '/api/bongos/npm-release/work']) {
+    const { divert, out } = rig();
+    await run(divert, req({ originalUrl: url }));
+    assert.equal(out.forwarded, 1, url);
+  }
+});
+
+test('a CLI or API call (an Authorization header) is never forwarded', async () => {
+  const { divert, out } = rig();
+  const r = await run(divert, req({ headers: { cookie: 'sid=good; bongos_preview=1.19.1000', authorization: 'Bearer abc' } }));
+  assert.equal(out.forwarded, 0);
+  assert.equal(r.passed, 1);
+  assert.equal(out.gateRuns, 0, 'decided before any gate runs');
+});
+
+test('a cookie for a preview that is not running is dropped and the live hall answers', async () => {
+  for (const status of [{ state: 'idle', version: null }, { state: 'starting', version: '1.19.1000' }, { state: 'running', version: '1.19.999' }, { state: 'failed', version: '1.19.1000' }]) {
+    const { divert, out } = rig({ status });
+    const r = await run(divert, req());
+    assert.equal(out.forwarded, 0, JSON.stringify(status));
+    assert.equal(r.passed, 1);
+    assert.deepEqual(r.set, [['Set-Cookie', clearCookie()]]);
+  }
+});
+
+test('the clearing cookie expires the steering cookie for the whole site', () => {
+  assert.match(clearCookie(), /^bongos_preview=; Path=\/; Max-Age=0/);
+});

package/tests/npm_release_preview_env.mjs

@@ -0,0 +1,100 @@
+// tests/npm_release_preview_env.mjs — the environment a version preview runs in (task 1004300).
+//
+// WHAT IS AT RISK. The preview is another Bongos process on the live droplet. If its
+// environment is a COPY of ours with a few names removed, the next secret anyone adds to the
+// live environment (a new webhook, a new API key) is silently inherited by a process that
+// runs an old version against a copy of production data. So the property under test is
+// deny-by-default: a name we have never heard of does not get through.
+//
+// Run:  node --test tests/npm_release_preview_env.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { buildPreviewEnv, CARRIED, POLLERS_OFF, MODULES_OFF, PREVIEW_DB } = require('../modules/npm-release/preview/env.js');
+
+const LIVE = {
+  PATH: '/usr/bin',
+  NODE_ENV: 'production',
+  PGHOST: '/var/run/postgresql',
+  PGUSER: 'hall',
+  PORT: '3000',
+  HOST: '0.0.0.0',
+  HOME: '/home/hall',
+  PGDATABASE: 'live_db',
+  DATABASE_URL: 'postgres://live/live_db',
+  GITHUB_TOKEN: 'ghp_x',
+  GITHUB_CLIENT_SECRET: 'cs',
+  DISCORD_BOT_TOKEN: 'dt',
+  DISCORD_WEBHOOK_URL: 'https://discord.invalid/hook',
+  ANTHROPIC_API_KEY: 'sk-ant-x',
+  GEMINI_API_KEY: 'g',
+  NPM_TOKEN: 'npm_x',
+  DO_TOKEN: 'do',
+  A_SECRET_ADDED_NEXT_YEAR: 'nobody-listed-me',
+};
+
+const build = () => buildPreviewEnv({ env: LIVE, port: 3190, scratchHome: '/tmp/scratch-home' });
+
+test('deny by default: only the allow-listed names come across from the live environment', () => {
+  const out = build();
+  for (const k of ['GITHUB_TOKEN', 'GITHUB_CLIENT_SECRET', 'DISCORD_BOT_TOKEN', 'DISCORD_WEBHOOK_URL',
+    'ANTHROPIC_API_KEY', 'GEMINI_API_KEY', 'NPM_TOKEN', 'DO_TOKEN', 'DATABASE_URL', 'A_SECRET_ADDED_NEXT_YEAR']) {
+    assert.equal(k in out, false, `${k} must not reach the preview`);
+  }
+  // Every name in the output is either carried by the allow-list or one the builder sets itself.
+  const own = new Set([...CARRIED, 'PORT', 'HOST', 'HOME', 'PGDATABASE', 'CHAT_DRY_RUN', ...POLLERS_OFF, ...MODULES_OFF]);
+  for (const k of Object.keys(out)) assert.ok(own.has(k), `unexpected name ${k}`);
+});
+
+test('the returned object is a fresh one, never the live environment', () => {
+  const out = build();
+  assert.notEqual(out, LIVE);
+  out.PATH = 'changed';
+  assert.equal(LIVE.PATH, '/usr/bin');
+});
+
+test('what a process needs to boot and reach Postgres is carried', () => {
+  const out = build();
+  assert.equal(out.PATH, '/usr/bin');
+  assert.equal(out.NODE_ENV, 'production');
+  assert.equal(out.PGHOST, '/var/run/postgresql');
+  assert.equal(out.PGUSER, 'hall');
+});
+
+test('it binds its own loopback port and points at the copy, never the live database', () => {
+  const out = build();
+  assert.equal(out.PORT, '3190');
+  assert.equal(out.HOST, '127.0.0.1');
+  assert.equal(out.PGDATABASE, PREVIEW_DB);
+  assert.notEqual(out.PGDATABASE, LIVE.PGDATABASE);
+});
+
+test('HOME is the empty scratch directory, so the real home config is not found', () => {
+  assert.equal(build().HOME, '/tmp/scratch-home');
+});
+
+test('outbound chat is a dry run and every poller is switched off', () => {
+  const out = build();
+  assert.equal(out.CHAT_DRY_RUN, '1');
+  for (const k of POLLERS_OFF) assert.equal(out[k], '1', k);
+  assert.equal(POLLERS_OFF.length, 9);
+});
+
+test('the modules that talk outward are off, and a preview cannot offer previews', () => {
+  const out = build();
+  for (const k of ['BONGOS_MODULE_DISCORD', 'BONGOS_MODULE_AGENTS', 'BONGOS_MODULE_PROVISIONING', 'BONGOS_MODULE_NPM_RELEASE']) {
+    assert.equal(out[k], '0', k);
+  }
+});
+
+test('NODE_ENV defaults to production when the live process set none', () => {
+  const out = buildPreviewEnv({ env: { PATH: '/bin' }, port: 1, scratchHome: '/h' });
+  assert.equal(out.NODE_ENV, 'production');
+});
+
+test('a missing port or scratch home is refused rather than guessed', () => {
+  assert.throws(() => buildPreviewEnv({ env: LIVE, scratchHome: '/h' }), /port/);
+  assert.throws(() => buildPreviewEnv({ env: LIVE, port: 1 }), /scratchHome/);
+});