@bongos/core 1.25.21 → 1.25.23

package/tests/hall_palette.mjs

@@ -35,10 +35,13 @@ const SHELL_SRC = read('shell.js');
 // SAME stub every time — real enough to fire DOM events at and read innerHTML
 // back from, which the pure-compute-only harness never needed before task 1003460
 // wired a real fetch() into the input handler.
-function bootPalette({ navItems = [], visibleIds = ['nav-profile', 'nav-work', 'shell-user'], modules = null, fetchImpl = undefined } = {}) {
+// `asleepIds`: nav ids the shell has marked asleep (.nav-item--asleep) while founding.
+function bootPalette({ navItems = [], visibleIds = ['nav-profile', 'nav-work', 'shell-user'], asleepIds = [], modules = null, fetchImpl = undefined } = {}) {
   const registry = {};
+  const asleepClass = (id) => ({ contains: (c) => c === 'nav-item--asleep' && asleepIds.includes(id) });
   const makeNav = (it) => ({
     hidden: !!it.hidden,
+    classList: asleepClass(`nav-${it.id}`),
     target: it.external ? '_blank' : '',
     getAttribute: (n) => (n === 'href' ? it.href : null),
     querySelector: (sel) => (sel === '.nav-item__label' ? { textContent: it.label } : null),
@@ -69,7 +72,7 @@ function bootPalette({ navItems = [], visibleIds = ['nav-profile', 'nav-work', '
     documentElement: { classList: { add() {}, remove() {} } },
     getElementById(id) {
       if (id === 'topbar-jump' || id === 'topbar-jump-kbd') return stubEl();
-      return visibleIds.includes(id) ? { hidden: false } : null;
+      return visibleIds.includes(id) ? { hidden: false, classList: asleepClass(id) } : null;
     },
     querySelectorAll(sel) {
       if (sel === '#app-sidebar .nav-item') return navItems.map(makeNav);
@@ -429,3 +432,57 @@ test('closing and reopening clears the cache — a fresh open may see new DB sta
 
   assert.equal(calls.length, 2, 'a fresh open must not trust a memo carried over from the previous one');
 });
+
+// ---- founding: a sleeping room is not a destination (task 1005285) ----------
+// While a project is founded the shell marks each room the server says sleeps
+// (/me.founding_mode.asleep, keyed by nav id) with .nav-item--asleep and hides it;
+// the server refuses its page too. The jump list must not offer it either, or the
+// founder is listed a room that is not open. Which rooms sleep is the server's own
+// shapeFoundingMode, never a list typed here.
+const require = (await import('node:module')).createRequire(import.meta.url);
+const foundingMode = require('../modules/onboarding/founding-mode.js');
+const ROOMS = [
+  { id: 'home', label: 'Home', href: '/' },
+  { id: 'work', label: 'Tasks', href: '/work' },
+  { id: 'goals', label: 'Goals', href: '/goals' },
+  { id: 'goal-map', label: 'Sky', href: '/goal-map' },
+  { id: 'board-room', label: 'Board Room', href: '/board-room' },
+  { id: 'collab', label: 'Collab', href: '/collab' },
+  { id: 'roster', label: 'Builders', href: '/roster' },
+  { id: 'profile', label: 'Profile', href: '/profile' },
+  { id: 'primer', label: 'Primer', href: '/primer' },
+];
+const asleepAt = (stage) => Object.keys(foundingMode.shapeFoundingMode({ active: 'true', stage }).asleep).map((id) => `nav-${id}`);
+const navIds = ROOMS.map((r) => `nav-${r.id}`).concat('shell-user');
+const pages = (P) => P.compute('').filter((r) => r.group === 'Pages').map((r) => r.label);
+
+test('founding: a room the server says sleeps is neither a page nor a section in the jump list (task 1005285)', () => {
+  const asleepIds = asleepAt('scope');
+  assert.deepEqual([...asleepIds].sort(), ['nav-collab', 'nav-goal-map', 'nav-goals', 'nav-roster', 'nav-work'],
+    'at scope the server puts Tasks, Goals, Sky, Collab and Builders to sleep');
+  const P = bootPalette({ navItems: ROOMS.map((r) => ({ ...r })), visibleIds: navIds, asleepIds });
+  assert.deepEqual(pages(P), ['Home', 'Board Room', 'Profile', 'Primer'], 'only the open rooms are listed');
+  const all = P.compute('');
+  assert.ok(!all.some((r) => r.group === 'Tasks'), 'no Tasks tab is offered while Tasks sleeps');
+  assert.ok(all.some((r) => r.group === 'Profile') && all.some((r) => r.group === 'Primer'), 'an open room keeps its sections');
+  assert.ok(!P.compute('tas').some((r) => r.href === '/work' || r.href.indexOf('/work#') === 0), 'searching for it finds nothing that goes there');
+});
+
+test('founding: a room opens in the jump list the moment its stage is behind (task 1005285)', () => {
+  const asleepIds = asleepAt('charter'); // scope and strategize are done: Goals, Sky and Tasks woke
+  const P = bootPalette({ navItems: ROOMS.map((r) => ({ ...r })), visibleIds: navIds, asleepIds });
+  assert.deepEqual(pages(P), ['Home', 'Tasks', 'Goals', 'Sky', 'Board Room', 'Profile', 'Primer']);
+  assert.ok(P.compute('').some((r) => r.group === 'Tasks'), 'the woken room brings its tabs');
+});
+
+test('a project that is not founding: the jump list is exactly what it was (task 1005285)', () => {
+  const P = bootPalette({ navItems: ROOMS.map((r) => ({ ...r })), visibleIds: navIds });
+  assert.deepEqual(pages(P), ROOMS.map((r) => r.label));
+  assert.ok(P.compute('').some((r) => r.group === 'Tasks'));
+});
+
+test('the jump list reads the sleeping mark, the one shell.js stamps from /me (task 1005285)', () => {
+  assert.match(SHELL_SRC, /classList\.add\('nav-item--asleep'\)/, 'shell.js marks a sleeping room with this class');
+  assert.match(PALETTE_SRC, /contains\('nav-item--asleep'\)/, 'and the palette skips exactly that class');
+  assert.doesNotMatch(PALETTE_SRC.replace(/\/\/.*$/gm, ''), /founding|asleepRooms|WAKES/, 'the palette never works out which rooms sleep on its own');
+});

package/tests/project_facts.mjs

@@ -0,0 +1,158 @@
+// tests/project_facts.mjs — the project's own facts, carried from the hub, and each reward
+// option's real implications at the point of choice (task 1005129).
+//
+// Everything RUNS: the hub's real companion line (provisioning.js SETTINGS_COMPANION_ENV →
+// project-facts.js) decoded by the project's real reader, the real soft-limit table carried
+// as data, and the project's facts + options over an in-memory project_settings store and
+// a fake `lifecycle.payTypeGates` port built from the REAL gate table.
+//
+// Run:  node --test tests/project_facts.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const provisioning = require('../modules/provisioning/provisioning.js');
+const hub = require('../modules/provisioning/project-facts.js');
+const pf = require('../modules/onboarding/project-facts.js');
+const gatesLib = require('../modules/lifecycle/pay-type-gates.js');
+const { PAY_TYPE_LABELS } = require('../modules/lifecycle/pay-terms.js');
+
+// The real gate verdicts with nothing on file (or with the given pay types cleared).
+function payGates(cleared = []) {
+  return {
+    labels: PAY_TYPE_LABELS,
+    readGates: async () => {
+      const types = [...Object.keys(gatesLib.REQUIREMENTS), 'eu_labour'];
+      return types.map((p) => gatesLib.withoutEvidence(gatesLib.gateVerdict(p, cleared.includes(p)
+        ? gatesLib.requirementIds(p).map((requirement) => ({ pay_type: p, requirement, state: 'cleared' })) : [])));
+    },
+  };
+}
+
+function project({ detail, gates = payGates() } = {}) {
+  const store = new Map();
+  const line = detail ? provisioning.SETTINGS_COMPANION_ENV.PROJECT_FACTS({ detail }) : '';
+  return {
+    store,
+    deps: () => ({
+      getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+      setSetting: async (k, v) => { store.set(k, String(v)); },
+      factsMarker: pf.factsMarker({ projectFacts: line }),
+      payGates: gates,
+      now: () => new Date('2026-11-13T12:00:00Z'),
+    }),
+  };
+}
+
+test('the hub carries only the facts a stage reads, and the reward rules as data', () => {
+  const line = provisioning.SETTINGS_COMPANION_ENV.PROJECT_FACTS({ detail: {
+    home_country: 'DE', builder_geography: 'global', entity: 'nonprofit', minors_on_board: false,
+    reward_intents: ['cash', 'equity'], framing: 'managed', project_state: 'new',
+  } });
+  const m = JSON.parse(Buffer.from(line, 'base64url').toString('utf8'));
+  assert.deepEqual(Object.keys(m.facts).sort(), ['builder_geography', 'entity', 'home_country', 'minors_on_board', 'reward_intents']);
+  assert.ok(!('framing' in m.facts), 'nothing a stage does not read crosses');
+  assert.ok(m.rules.length > 0 && m.rules.every((r) => r.options.some((o) => o.startsWith('reward_intents'))), 'only reward rules ride along');
+  assert.deepEqual(m.rules.map((r) => r.id), hub.REWARD_RULES.map((r) => r.id), 'read from the soft-limit table, never rewritten');
+  assert.equal(provisioning.SETTINGS_COMPANION_ENV.PROJECT_FACTS({ detail: {} }), '', 'nothing answered: an empty line, not a guess');
+  assert.equal(provisioning.SETTINGS_COMPANION_ENV.PROJECT_FACTS({}), '');
+});
+
+test('the project seeds its own copy once, as carried over; the founder\'s edit wins after', async () => {
+  const p = project({ detail: { home_country: 'US', home_region: 'US-CA', builder_geography: 'us-only' } });
+  let r = await pf.readFacts(p.deps());
+  const geo = r.facts.find((f) => f.key === 'builder_geography');
+  assert.equal(geo.value, 'us-only');
+  assert.equal(geo.origin, 'carried_over');
+  assert.deepEqual(r.unanswered, ['minors_on_board', 'entity', 'reward_intents'], 'never answered reads as not answered');
+  const w = await pf.setFacts({ builder_geography: 'global' }, 1, p.deps());
+  assert.equal(w.ok, true);
+  r = await pf.readFacts(p.deps());
+  assert.equal(r.facts.find((f) => f.key === 'builder_geography').value, 'global', 'the copy is editable, not a frozen snapshot');
+  assert.equal(r.facts.find((f) => f.key === 'builder_geography').origin, 'founder');
+  assert.equal(r.facts.find((f) => f.key === 'home_country').origin, 'carried_over');
+  // Un-answering goes back to "not answered".
+  await pf.setFacts({ home_region: null }, 1, p.deps());
+  assert.ok((await pf.readFacts(p.deps())).unanswered.includes('home_region'));
+});
+
+test('a project not made through the hub has every fact "not answered" and is not refused', async () => {
+  const p = project({});
+  const r = await pf.readOptions(p.deps());
+  assert.equal(r.unanswered.length, 6);
+  assert.equal(r.facts.every((f) => f.value === null), true);
+  assert.ok(r.options.length > 0, 'the options are still stated, from the enforced table');
+  assert.ok(r.options.every((o) => o.facts.length === 0), 'no fact note fires on an answer nobody gave');
+});
+
+test('every option states what the server enforces and the facts beside it, kept apart', async () => {
+  const p = project({ detail: { home_country: 'US', builder_geography: 'us-eu', entity: 'nonprofit', minors_on_board: true } });
+  const r = await pf.readOptions(p.deps());
+  const cash = r.options.find((o) => o.pay_type === 'cash');
+  assert.equal(cash.status, 'needs_setup');
+  assert.equal(cash.enforced.cleared, false);
+  assert.deepEqual(cash.enforced.missing, ['Processor onboarding done', 'Tax details collected', 'Age check passed', 'Sanctions screening done', 'Signed pay rule on file'],
+    'the five things cash needs, from the gate table');
+  assert.ok(cash.facts.some((n) => /EU aren't available yet/.test(n.reason)), 'builders in the EU: a fact about cash');
+  assert.ok(cash.facts.some((n) => /13 to 15/.test(n.reason)), 'minors on board: a fact about cash');
+  assert.ok(cash.facts.every((n) => n.enforced === false), 'a soft limit is never shown as enforced');
+  const equity = r.options.find((o) => o.pay_type === 'equity');
+  assert.ok(equity.facts.some((n) => n.effect === 'grey' && /nonprofit/i.test(n.reason)));
+  assert.equal(equity.advised_against, true);
+  // A blocked option is SHOWN, with its reason.
+  const eu = r.options.find((o) => o.pay_type === 'eu_labour');
+  assert.ok(eu, 'EU labour is listed, not hidden');
+  assert.equal(eu.status, 'closed');
+  assert.equal(eu.enforced.never, true);
+  assert.match(eu.enforced.reason, /refuses/);
+  assert.equal(eu.label, 'Paying builders in the EU');
+  // A cleared gate reads as allowed.
+  const q = project({ gates: payGates(['self_managed']) });
+  assert.equal((await pf.readOptions(q.deps())).options.find((o) => o.pay_type === 'self_managed').status, 'open');
+});
+
+test('changing a fact re-checks every option and says what it changed', async () => {
+  const p = project({ detail: { home_country: 'US', builder_geography: 'us-only' } });
+  let r = await pf.readOptions(p.deps());
+  assert.equal(r.options.find((o) => o.pay_type === 'cash').facts.length, 0);
+  const w = await pf.setFacts({ builder_geography: 'global' }, 1, p.deps());
+  const c = w.changed.find((x) => x.pay_type === 'cash');
+  assert.ok(c, 'cash is named as changed');
+  assert.ok(c.new_notes.some((n) => /EU/.test(n)));
+  r = await pf.readOptions(p.deps());
+  assert.ok(r.options.find((o) => o.pay_type === 'cash').facts.length > 0, 'the read reflects the new fact at once');
+  const back = await pf.setFacts({ builder_geography: 'us-only' }, 1, p.deps());
+  assert.ok(back.changed.find((x) => x.pay_type === 'cash').gone_notes.length > 0, 'and says when a note no longer applies');
+});
+
+test('a bad fact is refused with its reason; nothing is written', async () => {
+  const p = project({ detail: { home_country: 'US' } });
+  await pf.readFacts(p.deps());
+  const before = p.store.get(pf.FACTS_KEY);
+  assert.equal((await pf.setFacts({ nope: 1 }, 1, p.deps())).reason, 'unknown_fact');
+  assert.equal((await pf.setFacts({ builder_geography: 'mars' }, 1, p.deps())).reason, 'bad_fact');
+  assert.equal((await pf.setFacts({ home_region: 'CA-ON' }, 1, p.deps())).reason, 'region_not_in_country');
+  assert.equal((await pf.setFacts({ reward_intents: ['gold'] }, 1, p.deps())).reason, 'bad_fact');
+  assert.equal(p.store.get(pf.FACTS_KEY), before);
+});
+
+test('with no pay-rules module nothing is claimed as enforced', async () => {
+  const p = project({ detail: { entity: 'nonprofit' }, gates: null });
+  const r = await pf.readOptions(p.deps());
+  assert.equal(r.rules_module, false);
+  assert.ok(r.options.every((o) => o.enforced === null && o.status === 'no_rules_module'));
+  assert.ok(r.options.find((o) => o.pay_type === 'equity').facts.length > 0, 'the facts still speak');
+  assert.match(pf.optionsMarkdown(r), /nothing below is enforced by the server/);
+});
+
+test('the session read explains the rules and tells it never to add one', async () => {
+  const p = project({ detail: { home_country: 'US', builder_geography: 'global' } });
+  const md = pf.optionsMarkdown(await pf.readOptions(p.deps()));
+  assert.match(md, /never add a rule of your own/);
+  assert.match(md, /Closed \(enforced\)/);
+  assert.match(md, /Fact, not a rule: /);
+  assert.match(md, /Where its builders are: global \(from project creation, not yet confirmed\)/);
+  assert.match(md, /not answered/);
+});

package/tests/projects_hub.mjs

@@ -2240,7 +2240,7 @@ test('the wizard\'s own structures wear the world: hairline fields, cells of one
   assert.match(SCRIPT, /body: JSON\.stringify\(\{\s*slug: state\.slug,/, 'the filing still carries the slug first');
   assert.match(SCRIPT, /hosting_shape: 'cloud-host',/, 'the shape is unchanged');
   assert.match(SCRIPT, /target_ref: state\.owner \+ '\/' \+ state\.repo,/, 'the repo ref is unchanged');
-  assert.match(SCRIPT, /onboard_mode: state\.mode === 'adopt' \? 'adopt' : 'greenfield'/, 'the onboard mode is unchanged');
+  assert.match(SCRIPT, /onboard_mode: state\.mode === 'adopt' \|\| state\.folderUploaded \? 'adopt' : 'greenfield'/, 'the onboard mode: adopt, or a repo made from an uploaded folder (task 1005282)');
   // the kit walks every step and files against the stub
   const states = JSON.parse(fs.readFileSync(path.join(LANDING, 'projects.states.json'), 'utf8')).states;
   for (const s of ['named', 'ready', 'demo', 'checks-filled', 'row-code', 'row-extras', 'look', 'create-blocked', 'done']) assert.ok(states['in-new-' + s], `the ${s} state has a kit state`);

package/tests/provision_settings_apply.mjs

@@ -82,6 +82,7 @@ ${NEUTRAL_PREFIX}_DEMO_HOURS=
 ${NEUTRAL_PREFIX}_SHIP_MODE=
 ${NEUTRAL_PREFIX}_TEST_PROJECT=
 ${NEUTRAL_PREFIX}_GUIDE_HANDOFF=
+${NEUTRAL_PREFIX}_PROJECT_FACTS=
 ${NEUTRAL_PREFIX}_HUB_UPGRADE_URL=
 `;
 
@@ -153,7 +154,7 @@ t('settingsEnvVarsFor: the runner pushes the SAME pair webEnvBody writes at stan
     // the birth marker and a demo's box (task 1004506), empty on an un-stamped row
     [`${NEUTRAL_PREFIX}_FOUNDING_BIRTH`]: '', [`${NEUTRAL_PREFIX}_FOUNDING_GENESIS`]: '', [`${NEUTRAL_PREFIX}_DEMO_PEOPLE`]: '', [`${NEUTRAL_PREFIX}_DEMO_HOURS`]: '',
     // the wizard's ship mode (task 1004629), empty when none was picked
-    [`${NEUTRAL_PREFIX}_SHIP_MODE`]: '', [`${NEUTRAL_PREFIX}_TEST_PROJECT`]: '', [`${NEUTRAL_PREFIX}_GUIDE_HANDOFF`]: '',
+    [`${NEUTRAL_PREFIX}_SHIP_MODE`]: '', [`${NEUTRAL_PREFIX}_TEST_PROJECT`]: '', [`${NEUTRAL_PREFIX}_GUIDE_HANDOFF`]: '', [`${NEUTRAL_PREFIX}_PROJECT_FACTS`]: '',
     // where the hall's Update button goes (task 1004608), empty when no hub origin resolves
     [`${NEUTRAL_PREFIX}_HUB_UPGRADE_URL`]: '',
   });

package/tests/provisioning_settings_env.mjs

@@ -128,7 +128,7 @@ t('settingsEnvVars is the single source both legs derive from — same keys, sam
     // route never stamped, which is every row made before it shipped (spec D8).
     CLOUDBONGOS_FOUNDING_BIRTH: '', CLOUDBONGOS_FOUNDING_GENESIS: '', CLOUDBONGOS_DEMO_PEOPLE: '', CLOUDBONGOS_DEMO_HOURS: '',
     // The wizard's ship mode (task 1004629): empty when none was picked.
-    CLOUDBONGOS_SHIP_MODE: '', CLOUDBONGOS_TEST_PROJECT: '', CLOUDBONGOS_GUIDE_HANDOFF: '',
+    CLOUDBONGOS_SHIP_MODE: '', CLOUDBONGOS_TEST_PROJECT: '', CLOUDBONGOS_GUIDE_HANDOFF: '', CLOUDBONGOS_PROJECT_FACTS: '',
   });
   // varsOf splits on '=', so an empty value reads as '' on both sides — the point
   // of the comparison is that the standup lines carry exactly the same key set.
@@ -137,7 +137,7 @@ t('settingsEnvVars is the single source both legs derive from — same keys, sam
     X_PLATFORM_VISIBILITY: 'public', X_JOINABILITY: 'apply', X_VISIBILITY: 'public', X_JOIN_GRANT: 'full',
     X_ARTIST_GATE: 'strict', X_ARTIST_GATE_SINCE: '', X_SPEND_PAYER: 'none',
     X_LOOK: 'own', X_NIGHT_TINT: 'on', X_LOOK_ACCENT: '', X_LOGO_URL: '',
-    X_FOUNDING_BIRTH: '', X_FOUNDING_GENESIS: '', X_DEMO_PEOPLE: '', X_DEMO_HOURS: '', X_SHIP_MODE: '', X_TEST_PROJECT: '', X_GUIDE_HANDOFF: '',
+    X_FOUNDING_BIRTH: '', X_FOUNDING_GENESIS: '', X_DEMO_PEOPLE: '', X_DEMO_HOURS: '', X_SHIP_MODE: '', X_TEST_PROJECT: '', X_GUIDE_HANDOFF: '', X_PROJECT_FACTS: '',
   }, 'defaults, explicitly');
 });
 

package/tests/public_landing_projects.mjs

@@ -252,12 +252,34 @@ test('the repo is named as text from the server read, never a guessed link (task
 });
 
 test('the create-repo response keeps the html_url it already returned', async () => {
+  // EXECUTED, not read (task 1005282 moved the response handling into repoMade(), shared
+  // with the folder upload): the served page's repo create runs in a vm against a stub
+  // fetch, and the URL GitHub returned must land on the draft and be saved.
   const { body } = await request('/projects', 'game.test.local');
-  const fn = (body.match(/function ensureFreshRepo\(\)\s*\{([\s\S]*?)\n    \}/) || [, ''])[1];
-  assert.ok(fn, 'ensureFreshRepo() must be extractable');
-  assert.match(fn, /data\.repo && data\.repo\.html_url/, 'the URL is read off the response, not dropped');
-  assert.match(fn, /state\.repoUrl = made/, 'and stored on the draft so a resume keeps it');
-  assert.match(fn, /saveDraft\(\)/, 'the draft is persisted after the URL lands on state');
+  const src = body.replace(/\r\n/g, '\n');
+  const s = src.indexOf('    function ensureFreshRepo() {');
+  const e = s < 0 ? -1 : src.indexOf("    $('doCreate').addEventListener('click'", s);
+  assert.ok(s > 0 && e > s, 'ensureFreshRepo() and its response handler must be extractable');
+  const vm = (await import('node:vm')).default;
+  let saves = 0;
+  const sandbox = {
+    API: '/api/bongos', JSON, String, Promise, Error,
+    state: { mode: 'greenfield', repo: 'mercury', owner: 'founder' },
+    repoAccess: true, hopForRepoAccess: () => false, syncHome() {}, paintFolder() {},
+    saveDraft() { saves++; sandbox.savedUrl = sandbox.state.repoUrl; },
+    fetch: async () => ({ ok: true, status: 201, json: async () => ({ repo: { full_name: 'founder/mercury', html_url: 'https://github.com/founder/mercury' } }) }),
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(src.slice(s, e), sandbox);
+  await sandbox.ensureFreshRepo();
+  assert.equal(sandbox.state.repoUrl, 'https://github.com/founder/mercury', 'the URL is read off the response, not dropped');
+  assert.equal(sandbox.savedUrl, 'https://github.com/founder/mercury', 'the draft is persisted after the URL lands on state');
+  assert.ok(saves >= 1);
+  // a URL that is not GitHub's own is never kept
+  sandbox.state = { mode: 'greenfield', repo: 'x', owner: 'founder' };
+  sandbox.fetch = async () => ({ ok: true, status: 201, json: async () => ({ repo: { full_name: 'founder/x', html_url: 'https://evil.example/x' } }) });
+  await sandbox.ensureFreshRepo();
+  assert.equal(sandbox.state.repoUrl, undefined);
 });
 
 /* ── The address step's three choices (task 1002898 N2 / N8 / N10) ───────────

package/tests/render_sandbox.mjs

@@ -132,10 +132,13 @@ await ta('a new app with a database: the app, then its sandbox — free, follows
   assert.equal(sb.branch, 'main');
   assert.equal(sb.autoDeploy, 'yes', 'the sandbox follows every merge');
   assert.equal(sb.repo, 'https://github.com/example-owner/demo');
-  assert.deepEqual(sb.envVars, [
+  const pageKey = sb.envVars.find((v) => v.key === 'BONGOS_SANDBOX_PAGE_KEY');
+  assert.match(pageKey && pageKey.value, /^[0-9a-f]{48}$/, 'its own page key (task 1005291)');
+  assert.equal(h.inst.app_host.sandbox.pageKey, pageKey.value, 'kept on the row for the owner’s link');
+  assert.deepEqual(sb.envVars.filter((v) => v.key !== 'BONGOS_SANDBOX_PAGE_KEY'), [
     { key: 'BONGOS_SANDBOX', value: '1' },
     { key: 'DATABASE_URL', value: 'postgresql://u:p@dpg-new-a/demo_sandbox' },
-  ], 'its own database on the same server — never the live one');
+  ], 'its own database on the same server — never the live one, and no other key');
   // the second database is made with SQL on the app's server, existence checked first
   assert.equal(h.sqlRan.length, 2);
   assert.match(h.sqlRan[0].statements[0], /FROM pg_database WHERE datname = \$1/);
@@ -151,7 +154,7 @@ await ta('a new app with a database: the app, then its sandbox — free, follows
 await ta('an app with no database: the sandbox has none either, and says so', async () => {
   const h = harness({ host: { database: false } });
   assert.equal((await h.run()).ok, true);
-  assert.deepEqual(created(h, 'demo-sandbox').body.envVars, [{ key: 'BONGOS_SANDBOX', value: '1' }]);
+  assert.deepEqual(created(h, 'demo-sandbox').body.envVars.filter((v) => v.key !== 'BONGOS_SANDBOX_PAGE_KEY'), [{ key: 'BONGOS_SANDBOX', value: '1' }]);
   assert.equal(h.sqlRan.length, 0);
   assert.equal(h.inst.app_host.sandbox.database, 'none');
   assert.match(h.inst.app_host.sandbox.dbNote, /no database, so its sandbox has none/);
@@ -173,7 +176,7 @@ await ta('the database stage fails: the sandbox still runs, with no database, an
   const h = harness({ sql: async () => { throw new Error('permission denied to create database'); } });
   const out = await h.run();
   assert.equal(out.ok, true);
-  assert.deepEqual(created(h, 'demo-sandbox').body.envVars, [{ key: 'BONGOS_SANDBOX', value: '1' }], 'no DATABASE_URL at all — never the live one');
+  assert.deepEqual(created(h, 'demo-sandbox').body.envVars.filter((v) => v.key !== 'BONGOS_SANDBOX_PAGE_KEY'), [{ key: 'BONGOS_SANDBOX', value: '1' }], 'no DATABASE_URL at all — never the live one');
   const s = h.inst.app_host.sandbox;
   assert.equal(s.state, 'deploying');
   assert.equal(s.database, 'failed');

package/tests/sandbox_gate.mjs

@@ -0,0 +1,182 @@
+// tests/sandbox_gate.mjs — the sandbox's outbound gate and band (task 1005291; ADR 0406 §5).
+//
+// src/sandbox/ driven with fake fetch and fake http/https modules: no network, no provider,
+// no spend. The task's DONE WHEN, as written: with real keys lent, a read succeeds, and a
+// send, a charge and a write are each refused and logged. Plus: nothing changes outside a
+// sandbox; a sandbox page is visibly marked; the owner can see what was refused and which
+// real keys are lent (by name, never value); and the page says plainly what it cannot catch.
+//
+// Run:  node tests/sandbox_gate.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { EventEmitter } from 'node:events';
+
+const require = createRequire(import.meta.url);
+const { decide } = require('../src/sandbox/gate.js');
+const { install, isSandbox, pageHtml, PAGE } = require('../src/sandbox/index.js');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const LIVE = 'sk_live_51Habcdefghijklmnopqrstuv';
+const auth = (k) => ({ authorization: `Bearer ${k}` });
+
+console.log('the policy (decide):');
+await ta('a read to a known provider passes; a charge, a send and a write are refused, named by what they would do', () => {
+  assert.equal(decide({ method: 'GET', host: 'api.stripe.com', path: '/v1/customers', headers: auth(LIVE) }).allow, true);
+  const charge = decide({ method: 'POST', host: 'api.stripe.com', path: '/v1/payment_intents', headers: auth(LIVE) });
+  assert.deepEqual([charge.allow, charge.provider, charge.kind], [false, 'Stripe', 'charge']);
+  assert.match(charge.reason, /take or move a payment for real/);
+  const send = decide({ method: 'POST', host: 'api.sendgrid.com', path: '/v3/mail/send' });
+  assert.deepEqual([send.allow, send.kind], [false, 'send']);
+  const write = decide({ method: 'PATCH', host: 'api.github.com', path: '/repos/o/r/issues/1' });
+  assert.deepEqual([write.allow, write.kind], [false, 'write']);
+});
+await ta('a test-mode Stripe key is let through: it cannot move real money', () => {
+  assert.equal(decide({ method: 'POST', host: 'api.stripe.com', path: '/v1/charges', headers: auth('sk_test_abc') }).allow, true);
+  assert.equal(decide({ method: 'POST', host: 'api.stripe.com', path: '/v1/charges', headers: auth('rk_live_abc') }).allow, false, 'a restricted LIVE key is still refused writes');
+});
+await ta('a read some providers make by POST passes; their other writes do not', () => {
+  assert.equal(decide({ method: 'POST', host: 'api.notion.com', path: '/v1/databases/abc/query' }).allow, true);
+  assert.equal(decide({ method: 'POST', host: 'api.notion.com', path: '/v1/pages' }).allow, false);
+});
+await ta('a host the gate does not know passes — the gate covers what it knows, and the page says so', () => {
+  assert.equal(decide({ method: 'POST', host: 'example.org', path: '/x' }).allow, true);
+});
+
+console.log('\noutside a sandbox:');
+await ta('install() changes nothing unless BONGOS_SANDBOX=1', async () => {
+  const realFetch = async () => 'real';
+  const host = { fetch: realFetch };
+  const http = { request: () => 'r', get: () => 'g' };
+  assert.equal(isSandbox({}), false);
+  assert.equal(isSandbox({ BONGOS_SANDBOX: '1' }), true);
+  const out = install({ env: {}, fetchHost: host, http, https: http });
+  assert.equal(out.active, false);
+  assert.equal(host.fetch, realFetch, 'fetch untouched');
+  assert.equal(http.request(), 'r', 'http untouched');
+  let nexted = false;
+  out.middleware({}, {}, () => { nexted = true; });
+  assert.equal(nexted, true, 'the middleware passes straight through');
+});
+
+console.log('\nin a sandbox, with a real key lent:');
+const sent = [], lines = [];
+const fetchHost = { fetch: async (input, init = {}) => { sent.push({ via: 'fetch', url: String(input), method: init.method || 'GET' }); return { status: 200, ok: true }; } };
+function fakeHttp(name) {
+  return {
+    request(...args) { sent.push({ via: name, args }); const r = new EventEmitter(); r.end = () => r; return r; },
+    get(...args) { sent.push({ via: `${name}.get`, args }); const r = new EventEmitter(); r.end = () => r; return r; },
+  };
+}
+const http = fakeHttp('http'), https = fakeHttp('https');
+const env = { BONGOS_SANDBOX: '1', STRIPE_SECRET_KEY: LIVE, STRIPE_READ_KEY: 'rk_live_51Hrestrictedabcdefg', SENDGRID_API_KEY: 'SG.abcdefghijklmnop.qrstuvwxyz', PORT: '3000' };
+const sb = install({ env, fetchHost, http, https, write: (l) => lines.push(l) });
+
+await ta('a read succeeds', async () => {
+  sent.length = 0;
+  const r = await fetchHost.fetch('https://api.stripe.com/v1/customers?limit=3', { headers: auth(LIVE) });
+  assert.equal(r.status, 200);
+  assert.equal(sent.length, 1, 'the read went out');
+});
+await ta('a charge is refused (403, never sent) and logged', async () => {
+  sent.length = 0; lines.length = 0;
+  const r = await fetchHost.fetch('https://api.stripe.com/v1/payment_intents', { method: 'POST', headers: auth(LIVE), body: 'amount=500' });
+  assert.equal(r.status, 403);
+  const body = await r.json();
+  assert.equal(body.error.type, 'bongos_sandbox_refused');
+  assert.equal(sent.length, 0, 'nothing left the sandbox');
+  assert.match(lines[0], /^\[bongos-sandbox\] refused charge to Stripe: POST api\.stripe\.com\/v1\/payment_intents$/);
+});
+await ta('a send through an SDK’s https.request is refused with an error, never connects, and is logged', async () => {
+  sent.length = 0; lines.length = 0;
+  const req = https.request({ hostname: 'api.sendgrid.com', method: 'POST', path: '/v3/mail/send', headers: { authorization: 'Bearer SG.x' } });
+  const err = await new Promise((resolve) => { req.on('error', resolve); req.end('{}'); });
+  assert.equal(err.code, 'BONGOS_SANDBOX_REFUSED');
+  assert.equal(err.kind, 'send');
+  assert.equal(sent.length, 0, 'the real request was never made');
+  assert.match(lines[0], /refused send to SendGrid/);
+});
+await ta('a write is refused and logged; https.get (a read) still goes out', async () => {
+  sent.length = 0; lines.length = 0;
+  const r = await fetchHost.fetch(new URL('https://api.github.com/repos/o/r/issues'), { method: 'POST' });
+  assert.equal(r.status, 403);
+  assert.match(lines[0], /refused write to GitHub/);
+  https.get('https://api.github.com/repos/o/r');
+  assert.deepEqual(sent.map((s) => s.via), ['https.get']);
+});
+await ta('every refusal is kept, newest first, for the owner to see', () => {
+  assert.deepEqual(sb.refusals.slice(0, 3).map((r) => r.kind), ['write', 'send', 'charge']);
+});
+
+console.log('\nthe band and the page:');
+function fakeRes() {
+  const headers = { 'content-type': 'text/html; charset=utf-8' };
+  const res = { statusCode: 200, out: '', getHeader: (k) => headers[k.toLowerCase()], setHeader: (k, v) => { headers[k.toLowerCase()] = v; }, removeHeader: (k) => { delete headers[k.toLowerCase()]; } };
+  res.write = (c) => { res.out += c; return true; };
+  res.end = (c) => { if (c) res.out += c; res.ended = true; };
+  return { res, headers };
+}
+await ta('every HTML page carries the "Sandbox" band, with the count refused and a link', () => {
+  const { res } = fakeRes();
+  sb.middleware({ method: 'GET', url: '/' }, res, () => {});
+  res.end('<html><body><h1>Shop</h1></body></html>');
+  assert.match(res.out, /<body><div id="bongos-sandbox-band"/);
+  assert.match(res.out, /Sandbox — a test copy of this site\. Nothing here reaches real customers\./);
+  assert.doesNotMatch(res.out, /refused/, 'no count for passers-by');
+  assert.match(res.out, /href="\/__bongos\/sandbox"/);
+});
+await ta('a non-HTML answer is left alone', () => {
+  const { res, headers } = fakeRes();
+  headers['content-type'] = 'application/json';
+  sb.middleware({ method: 'GET', url: '/api' }, res, () => {});
+  res.end('{"a":1}');
+  assert.equal(res.out, '{"a":1}');
+});
+await ta('the sandbox page, for the owner: what was refused, which real keys are lent (names only), and what it cannot catch', () => {
+  const html = pageHtml({ items: sb.refusals }, env, { owner: true });
+  assert.match(html, /would take or move a payment/);
+  assert.match(html, /<code>STRIPE_SECRET_KEY<\/code>: Stripe — a full live secret key\. Prefer a restricted key with read access only\./);
+  assert.match(html, /<code>STRIPE_READ_KEY<\/code>: Stripe — a restricted live key/);
+  assert.ok(!html.includes(LIVE) && !html.includes('SG.abcdefghijklmnop'), 'never a key value');
+  assert.match(html, /Code that goes around them, or a provider it does not know, is not stopped\. A read-only key is the real protection/);
+});
+await ta('without the owner’s page key a visitor sees what a sandbox is — never the refusals or the lent keys', () => {
+  const KEY = 'a'.repeat(48);
+  env.BONGOS_SANDBOX_PAGE_KEY = KEY; // the env install() was given — the platform sets it on the sandbox
+  try {
+    for (const url of ['/__bongos/sandbox', '/__bongos/sandbox?key=wrong', `/__bongos/sandbox?key=${'b'.repeat(48)}`]) {
+      const { res } = fakeRes();
+      let nexted = false;
+      sb.middleware({ method: 'GET', url }, res, () => { nexted = true; });
+      assert.equal(nexted, false);
+      assert.match(res.out, /<h1>This is a sandbox<\/h1>/);
+      assert.match(res.out, /is not stopped/, 'the limits are public');
+      assert.doesNotMatch(res.out, /Refused calls|STRIPE_SECRET_KEY|payment_intents/, `${url} shows nothing private`);
+    }
+    const { res } = fakeRes();
+    sb.middleware({ method: 'GET', url: `/__bongos/sandbox?key=${KEY}` }, res, () => {});
+    assert.match(res.out, /Refused calls/);
+    assert.match(res.out, /STRIPE_SECRET_KEY/);
+  } finally { delete env.BONGOS_SANDBOX_PAGE_KEY; }
+});
+await ta('the owner page path is spelled the same in core and in the provisioning module', () => {
+  assert.equal(PAGE, '/__bongos/sandbox');
+});
+
+console.log('\nthe owner’s project page:');
+await ta('the owner’s sandbox status links to the sandbox’s own page with its page key', () => {
+  const rs = require('../modules/provisioning/render-sandbox.js');
+  const KEY = 'c'.repeat(48);
+  const host = (sb) => ({ id: 1, status: 'active', app_host: { platform: 'render', state: 'live', serviceId: 'srv-live0001', sandboxWanted: true,
+    sandbox: { state: 'live', serviceId: 'srv-sbx00001', serviceUrl: 'https://demo-sandbox.onrender.com', ...sb } } });
+  assert.equal(rs.sandboxStatus(host({ pageKey: KEY })).safety_page, `https://demo-sandbox.onrender.com${PAGE}?key=${KEY}`);
+  assert.equal(rs.sandboxStatus(host({})).safety_page, `https://demo-sandbox.onrender.com${PAGE}`, 'an older sandbox has no key: the public page');
+});
+
+console.log(`\nsandbox_gate: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);