@bongos/core 1.25.20 → 1.25.22

package/tests/render_promote.mjs

@@ -0,0 +1,309 @@
+// tests/render_promote.mjs — a person promotes what ran on the sandbox to the live app
+// (task 1005290; ADR 0406 §2). The runner leg (scripts/bongos/provision-render-promote.js)
+// is driven over the REAL Render client and a recording fake of Render's API; the web
+// tier's look (render-lookup.js lookupPromotion) over a fake fetch; the routes over
+// express with the module's seams stubbed. No network, no database, no spend.
+//
+// The task's DONE WHEN:
+//   • a shipped change is on the sandbox while the main site is unchanged — the sandbox
+//     setup switches the live service to manual deploys (tests/render_sandbox.mjs asserts
+//     the PATCH), and the look lists what ran on the sandbox since live's change;
+//   • promoting changes the main site — the live service is deployed at EXACTLY the chosen
+//     commit;
+//   • nothing reaches the main site without a recorded promotion — the record is written
+//     BEFORE Render is asked, a refusal sends nothing, and only the owner may press.
+//
+// Run:  node tests/render_promote.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+const { RenderApi } = require('../scripts/bongos/render-api.js');
+const { promoteInstance } = require('../scripts/bongos/provision-render-promote.js');
+const { lookupPromotion } = require('../modules/provisioning/render-lookup.js');
+const renderPromote = require('../modules/provisioning/render-promote.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 OURS = 'tea-ours00000001';
+const OLD = 'aaaaaaa1111111111111111111111111111111aa';
+const MID = 'bbbbbbb2222222222222222222222222222222bb';
+const NEW = 'ccccccc3333333333333333333333333333333cc';
+const BAD = 'ddddddd4444444444444444444444444444444dd';
+const dep = (id, commit, status, message = `task 100 - change ${commit.slice(0, 3)}`) => ({ deploy: { id, status, commit: { id: commit, message, createdAt: '2026-11-13T10:00:00Z' } } });
+
+function fakeRender(over = {}) {
+  const calls = [];
+  const answers = {
+    'GET /owners?limit=100': [{ owner: { id: OURS } }],
+    'GET /services/srv-live0001': { id: 'srv-live0001', name: 'demo', ownerId: OURS },
+    'GET /services/srv-sbx00001': { id: 'srv-sbx00001', name: 'demo-sandbox', ownerId: OURS },
+    'GET /services/srv-sbx00001/deploys?limit=50': [dep('dep-s4', BAD, 'build_failed'), dep('dep-s3', NEW, 'live'), dep('dep-s2', MID, 'deactivated'), dep('dep-s1', OLD, 'deactivated')],
+    'GET /services/srv-live0001/deploys?limit=10': [dep('dep-l1', OLD, 'live')],
+    'PATCH /services/srv-live0001': { id: 'srv-live0001', ownerId: OURS, autoDeploy: 'no' },
+    'POST /services/srv-live0001/deploys': { id: 'dep-live-new' },
+    ...over,
+  };
+  const fetchImpl = async (url, init) => {
+    const path = url.replace('https://api.render.com/v1', '');
+    const body = init.body ? JSON.parse(init.body) : null;
+    calls.push({ method: init.method, path, body });
+    const a = answers[`${init.method} ${path}`];
+    if (a === undefined) return { ok: false, status: 404, text: async () => '{"message":"not found"}' };
+    if (a instanceof Error) return { ok: false, status: 500, text: async () => JSON.stringify({ message: a.message }) };
+    return { ok: true, status: 200, text: async () => JSON.stringify(a) };
+  };
+  return { calls, fetchImpl };
+}
+
+function harness({ ask = {}, host = {}, render = {}, intent = {} } = {}) {
+  const r = fakeRender(render);
+  const order = [], promotions = [], cleared = [], logs = [];
+  let nextId = 1;
+  const inst = { id: 18, slug: 'demo', app_host: { platform: 'render', ownerId: OURS, serviceId: 'srv-live0001', state: 'live',
+    sandbox: { state: 'live', serviceId: 'srv-sbx00001' }, promote: { state: 'requested', commitId: NEW, expectLiveCommit: OLD, requestedBy: '7', ...ask }, ...host } };
+  const db = { query: async (text, params) => {
+    const t = text.replace(/\s+/g, ' ');
+    if (/INSERT INTO provisioning_promotions/.test(t)) {
+      order.push('record');
+      const row = { id: nextId++, commit_id: params[1], commit_message: params[2], from_commit_id: params[3], sandbox_deploy_id: params[4], requested_by: params[5], state: 'started' };
+      promotions.push(row);
+      return { rows: [{ id: row.id }] };
+    }
+    if (/UPDATE provisioning_promotions SET state = 'sent'/.test(t)) { Object.assign(promotions.find((p) => p.id === params[0]), { state: 'sent', render_deploy_id: params[1] }); return { rows: [] }; }
+    if (/UPDATE provisioning_promotions SET state = 'failed'/.test(t)) { Object.assign(promotions.find((p) => p.id === params[0]), { state: 'failed', error: params[1] }); return { rows: [] }; }
+    if (/SET app_host = COALESCE\(app_host, '\{\}'::jsonb\) \|\| \$2::jsonb/.test(t)) { inst.app_host = { ...inst.app_host, ...JSON.parse(params[1]) }; return { rows: [] }; }
+    if (/borrowed_key_enc = NULL/.test(t)) { cleared.push(params[0]); return { rows: [] }; }
+    return { rows: [] };
+  } };
+  const wrapped = { calls: r.calls, fetchImpl: async (url, init) => { if (init.method !== 'GET') order.push(`${init.method} ${url.replace('https://api.render.com/v1', '')}`); return r.fetchImpl(url, init); } };
+  const deps = { db, log: (l) => logs.push(l), secretBox: { decrypt: () => 'rnd_borrowed' },
+    renderApiFactory: ({ token, ownerId }) => new RenderApi({ token, ownerId, dryRun: false, fetchImpl: wrapped.fetchImpl }) };
+  const it = { id: 61, action: 'render-promote', borrowed_key_enc: 'v1.enc', created_at: new Date().toISOString(), ...intent };
+  return { r, inst, order, promotions, cleared, run: () => promoteInstance(inst, deps, it) };
+}
+const writes = (h) => h.r.calls.filter((c) => c.method !== 'GET').map((c) => `${c.method} ${c.path}`);
+
+console.log('the runner — promote:');
+await ta('promoting deploys EXACTLY the chosen commit to the live app, recorded first, live switched to manual', async () => {
+  const h = harness();
+  const out = await h.run();
+  assert.equal(out.ok, true, out.error);
+  assert.deepEqual(h.order, ['record', 'PATCH /services/srv-live0001', 'POST /services/srv-live0001/deploys'], 'the record comes before anything is sent');
+  const deploy = h.r.calls.find((c) => c.method === 'POST');
+  assert.deepEqual(deploy.body, { commitId: NEW }, 'that commit, not whatever main is now');
+  assert.deepEqual(h.r.calls.find((c) => c.method === 'PATCH').body, { autoDeploy: 'no' });
+  assert.equal(h.promotions.length, 1);
+  assert.deepEqual([h.promotions[0].commit_id, h.promotions[0].from_commit_id, h.promotions[0].requested_by, h.promotions[0].state, h.promotions[0].render_deploy_id],
+    [NEW, OLD, '7', 'sent', 'dep-live-new'], 'who, which change, from which, and what Render answered');
+  assert.equal(h.inst.app_host.liveAutoDeploy, 'off');
+  assert.equal(h.inst.app_host.promote.state, 'sent');
+  assert.deepEqual(h.cleared, [61], 'the key is cleared');
+});
+
+await ta('an older change that ran on the sandbox can be promoted too', async () => {
+  const h = harness({ ask: { commitId: MID } });
+  assert.equal((await h.run()).ok, true);
+  assert.deepEqual(h.r.calls.find((c) => c.method === 'POST').body, { commitId: MID });
+});
+
+await ta('a change that never ran on the sandbox is refused, and nothing is sent or recorded', async () => {
+  for (const commitId of [BAD, 'eeeeeee5555555555555555555555555555555ee']) {
+    const h = harness({ ask: { commitId } });
+    const out = await h.run();
+    assert.equal(out.ok, false);
+    assert.equal(out.terminal, true);
+    assert.match(out.error, /has not run on the sandbox/);
+    assert.deepEqual(writes(h), [], 'no write to Render');
+    assert.equal(h.promotions.length, 0);
+    assert.deepEqual(h.cleared, [61]);
+    assert.equal(h.inst.app_host.promote.state, 'failed');
+  }
+});
+
+await ta('if the live app moved since the owner looked, nothing is done', async () => {
+  const h = harness({ ask: { expectLiveCommit: MID } });
+  const out = await h.run();
+  assert.equal(out.ok, false);
+  assert.match(out.error, /changed since you looked/);
+  assert.deepEqual(writes(h), []);
+  assert.equal(h.promotions.length, 0);
+});
+
+await ta('a change already live is refused', async () => {
+  const h = harness({ ask: { commitId: OLD } });
+  const out = await h.run();
+  assert.match(out.error, /already on your live app/);
+  assert.deepEqual(writes(h), []);
+});
+
+await ta('Render refusing the deploy leaves a failed record, said plainly', async () => {
+  const h = harness({ render: { 'POST /services/srv-live0001/deploys': new Error('build minutes exhausted') } });
+  const out = await h.run();
+  assert.equal(out.ok, false);
+  assert.match(out.error, /build minutes exhausted/);
+  assert.equal(h.promotions[0].state, 'failed');
+  assert.match(h.promotions[0].error, /build minutes exhausted/);
+  assert.deepEqual(h.cleared, [61]);
+});
+
+await ta('no key, a stale key, no sandbox or no app: refused before Render is called', async () => {
+  const cases = [
+    [{ intent: { borrowed_key_enc: null } }, /no Render key/],
+    [{ intent: { created_at: new Date(Date.now() - 3600_000).toISOString() } }, /waited too long/],
+    [{ host: { sandbox: {} } }, /no sandbox/],
+    [{ host: { serviceId: null } }, /no app on Render/],
+    [{ ask: { commitId: 'not-a-commit' } }, /no change was chosen/],
+  ];
+  for (const [opts, re] of cases) {
+    const h = harness(opts);
+    const out = await h.run();
+    assert.equal(out.ok, false);
+    assert.match(out.error, re);
+    assert.equal(h.r.calls.length, 0, `no call to Render for ${re}`);
+  }
+});
+
+console.log('\nthe look — what is waiting:');
+function lookFetch(over = {}) {
+  const answers = {
+    '/services/srv-live0001': { id: 'srv-live0001', ownerId: OURS },
+    '/services/srv-sbx00001': { id: 'srv-sbx00001', ownerId: OURS },
+    '/services/srv-live0001/deploys?limit=10': [dep('dep-l1', OLD, 'live')],
+    '/services/srv-sbx00001/deploys?limit=30': [dep('dep-s4', BAD, 'build_failed'), dep('dep-s3', NEW, 'live'), dep('dep-s2', MID, 'deactivated'), dep('dep-s1', OLD, 'deactivated')],
+    ...over,
+  };
+  const seen = [];
+  const fetchImpl = async (url, init) => {
+    const path = url.replace('https://api.render.com/v1', '');
+    seen.push({ method: init.method, path });
+    const a = answers[path];
+    return { ok: a !== undefined, status: a !== undefined ? 200 : 404, json: async () => a };
+  };
+  return { seen, fetchImpl };
+}
+await ta('lists what ran on the sandbox since the change live runs, newest first, read-only', async () => {
+  const f = lookFetch();
+  const out = await lookupPromotion('rnd_k', { ownerId: OURS, liveServiceId: 'srv-live0001', sandboxServiceId: 'srv-sbx00001', fetchImpl: f.fetchImpl });
+  assert.equal(out.live.commit_id, OLD);
+  assert.deepEqual(out.waiting.map((w) => w.commit_id), [NEW, MID], 'the failed build is not waiting, and live’s own change is not');
+  assert.equal(out.waiting[0].short, NEW.slice(0, 7));
+  assert.ok(f.seen.every((c) => c.method === 'GET'), 'GET only');
+});
+await ta('a service from another workspace stops the look', async () => {
+  const f = lookFetch({ '/services/srv-sbx00001': { id: 'srv-sbx00001', ownerId: 'tea-theirs000001' } });
+  await assert.rejects(lookupPromotion('rnd_k', { ownerId: OURS, liveServiceId: 'srv-live0001', sandboxServiceId: 'srv-sbx00001', fetchImpl: f.fetchImpl }), /another workspace/);
+});
+await ta('live in step with the sandbox: nothing waits', async () => {
+  const f = lookFetch({ '/services/srv-live0001/deploys?limit=10': [dep('dep-l2', NEW, 'live')] });
+  const out = await lookupPromotion('rnd_k', { ownerId: OURS, liveServiceId: 'srv-live0001', sandboxServiceId: 'srv-sbx00001', fetchImpl: f.fetchImpl });
+  assert.deepEqual(out.waiting, []);
+});
+
+console.log('\nthe web tier:');
+await ta('enqueuePromote: the intent with the key and the chosen change on the row, in one statement', async () => {
+  const guard = require('../modules/provisioning/control-plane-guard.js');
+  const orig = guard.assertIntentAllowed;
+  guard.assertIntentAllowed = async () => {};
+  try {
+    const seen = [];
+    const db = { query: async (t, p) => { seen.push({ t: t.replace(/\s+/g, ' '), p }); return { rows: [{ id: 5 }] }; } };
+    await renderPromote.enqueuePromote(db, 18, { keyEnc: 'v1.enc', commitId: NEW, expectLiveCommit: OLD, requestedBy: 7 });
+    assert.equal(seen.length, 1);
+    assert.match(seen[0].t, /'render-promote'/);
+    const ask = JSON.parse(seen[0].p[3]);
+    assert.deepEqual([ask.state, ask.commitId, ask.expectLiveCommit, ask.requestedBy], ['requested', NEW, OLD, '7']);
+  } finally { guard.assertIntentAllowed = orig; }
+});
+await ta('promoteView: whether the owner can, and whether live still follows main', () => {
+  const ok = renderPromote.promoteView({ status: 'active', app_host: { platform: 'render', serviceId: 'srv-live0001', liveAutoDeploy: 'off', sandbox: { state: 'live', serviceId: 'srv-sbx00001' } } });
+  assert.deepEqual([ok.can, ok.live_follows_main], [true, false]);
+  const no = renderPromote.promoteView({ status: 'active', app_host: { platform: 'render', serviceId: 'srv-live0001' } });
+  assert.equal(no.can, false);
+  assert.match(no.reason, /no sandbox/);
+  assert.equal(no.live_follows_main, true);
+});
+
+// ---- the routes ----
+const provisioning = require('../modules/provisioning/provisioning.js');
+const secretBox = require('../src/bongos/secret-box.js');
+const kapi = require('../src/module-api.js');
+let instance = null, enq = [], builder = { id: 7 };
+provisioning.getInstanceById = async (_db, id) => (instance ? { ...instance, id } : null);
+provisioning.recordEvent = async () => {};
+renderPromote.enqueuePromote = async (_db, id, args) => { enq.push({ id, ...args }); return { intent: { id: 9 } }; };
+secretBox.isConfigured = () => true;
+secretBox.encrypt = (plain) => `v1.sealed(${plain.length})`;
+kapi.requireBuilder = (req, _res, next) => { req.builder = builder; next(); };
+kapi.logger = () => ({ error() {}, warn() {}, info() {}, debug() {} });
+Object.defineProperty(kapi, 'pool', { configurable: true, get: () => ({ query: async () => ({ rows: [] }) }) });
+require('../modules/provisioning/env-manifest.js').listEnvVars = async () => [];
+const f = lookFetch();
+const express = require('express');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => { res.fail = (code, o) => res.status(typeof o === 'number' ? o : (o && o.status) || 400).json({ error: { code, ...(typeof o === 'object' ? o : {}) } }); next(); });
+app.use('/api/bongos', require('../modules/provisioning/routes/render-standup.js')({ fetchImpl: f.fetchImpl }));
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+function call(method, path, body) {
+  return new Promise((resolve, reject) => {
+    const req = http.request(`${base}${path}`, { method, headers: { 'Content-Type': 'application/json' } }, (res) => {
+      let d = ''; res.on('data', (c) => { d += c; });
+      res.on('end', () => resolve({ status: res.statusCode, body: d ? JSON.parse(d) : null, raw: d }));
+    });
+    req.on('error', reject);
+    req.end(body ? JSON.stringify(body) : undefined);
+  });
+}
+const KEY = 'rnd_abcdefghijklmnopqrstuvwx';
+const READY = { owner_builder_id: 7, slug: 'demo', status: 'active', app_host: { platform: 'render', ownerId: OURS, serviceId: 'srv-live0001', state: 'live', sandbox: { state: 'live', serviceId: 'srv-sbx00001' } } };
+
+await ta('POST …/render/promote/look by the owner: what is waiting, the key never sent back', async () => {
+  instance = READY;
+  const r = await call('POST', '/provisioning/instances/18/render/promote/look', { key: KEY });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(r.body.waiting.map((w) => w.commit_id), [NEW, MID]);
+  assert.ok(!r.raw.includes(KEY));
+});
+await ta('POST …/render/promote by the owner: queued with ciphertext, the change and what live ran', async () => {
+  instance = READY; enq = [];
+  const r = await call('POST', '/provisioning/instances/18/render/promote', { key: KEY, commit_id: NEW, expect_live_commit: OLD });
+  assert.equal(r.status, 200, r.raw);
+  assert.deepEqual(enq, [{ id: 18, keyEnc: `v1.sealed(${KEY.length})`, commitId: NEW, expectLiveCommit: OLD, requestedBy: 7 }]);
+  assert.ok(!r.raw.includes(KEY));
+});
+await ta('nobody but the owner can promote or look (the stranger’s 404)', async () => {
+  instance = { ...READY, owner_builder_id: 99 }; enq = [];
+  assert.equal((await call('POST', '/provisioning/instances/18/render/promote', { key: KEY, commit_id: NEW })).status, 404);
+  assert.equal((await call('POST', '/provisioning/instances/18/render/promote/look', { key: KEY })).status, 404);
+  assert.equal(enq.length, 0);
+});
+await ta('no sandbox, or no chosen change: refused, nothing queued', async () => {
+  instance = { ...READY, app_host: { ...READY.app_host, sandbox: null } }; enq = [];
+  let r = await call('POST', '/provisioning/instances/18/render/promote', { key: KEY, commit_id: NEW });
+  assert.equal(r.status, 409);
+  assert.match(r.body.error.message, /no sandbox/);
+  instance = READY;
+  r = await call('POST', '/provisioning/instances/18/render/promote', { key: KEY, commit_id: 'main' });
+  assert.equal(r.status, 400);
+  assert.equal(enq.length, 0);
+});
+await ta('GET …/render carries whether the owner can promote', async () => {
+  instance = READY;
+  const r = await call('GET', '/provisioning/instances/18/render');
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(r.body.promote.can, true);
+  assert.deepEqual(r.body.promote.recent, []);
+});
+server.close();
+
+console.log(`\nrender_promote: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/render_sandbox.mjs

@@ -59,6 +59,7 @@ function fakeRender(over = {}) {
       serviceDetails: { url: LIVE_URL, plan: 'starter', runtime: 'python', region: 'oregon', envSpecificDetails: { buildCommand: 'pip install -r requirements.txt', startCommand: 'gunicorn app:app' } } },
     'GET /services/srv-sbx00001': { id: 'srv-sbx00001', name: 'demo-sandbox', ownerId: OURS, serviceDetails: { url: SB_URL, plan: 'free' } },
     'DELETE /services/srv-sbx00001': null,
+    'PATCH /services/srv-live0001': { id: 'srv-live0001', ownerId: OURS, autoDeploy: 'no' },
     [SB_NAME_Q]: [],
     ...over,
   };
@@ -122,16 +123,22 @@ await ta('a new app with a database: the app, then its sandbox — free, follows
   const h = harness();
   const out = await h.run();
   assert.equal(out.ok, true, out.error);
-  assert.deepEqual(writesTo(h.r.calls), ['POST /postgres', 'POST /services', 'POST /services'], 'database, live app, sandbox — and nothing else written');
+  assert.deepEqual(writesTo(h.r.calls), ['POST /postgres', 'POST /services', 'POST /services', 'PATCH /services/srv-live0001'],
+    'database, live app, sandbox, then the live app switched to manual deploys (task 1005290) — and nothing else written');
+  assert.deepEqual(h.r.calls.find((c) => c.method === 'PATCH').body, { autoDeploy: 'no' }, 'from now on only a promotion moves the live app');
+  assert.equal(h.inst.app_host.liveAutoDeploy, 'off');
   const sb = created(h, 'demo-sandbox').body;
   assert.equal(sb.serviceDetails.plan, 'free');
   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/);
@@ -147,17 +154,17 @@ 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/);
 });
 
-await ta('a linked (adopted) app: the sandbox copies its build, and the live service gets no write', async () => {
+await ta('a linked (adopted) app: the sandbox copies its build, and the live service only stops auto-deploying', async () => {
   const h = harness({ host: { mode: 'adopt', serviceId: 'srv-live0001', runtime: undefined, buildCommand: undefined, startCommand: undefined, database: undefined } });
   const out = await h.run();
   assert.equal(out.ok, true, out.error);
-  assert.deepEqual(writesTo(h.r.calls), ['POST /services'], 'the only write is the sandbox');
+  assert.deepEqual(writesTo(h.r.calls), ['POST /services', 'PATCH /services/srv-live0001'], 'the sandbox, and live switched to manual deploys');
   const sb = created(h, 'demo-sandbox').body;
   assert.equal(sb.serviceDetails.runtime, 'python');
   assert.equal(sb.serviceDetails.region, 'oregon');
@@ -169,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');
@@ -186,6 +193,7 @@ await ta('the sandbox failing never fails the app, and the key is still cleared'
   assert.equal(h.inst.app_host.state, 'deploying');
   assert.equal(h.inst.app_host.sandbox.state, 'failed');
   assert.match(h.inst.app_host.sandbox.error, /free instance limit reached/);
+  assert.ok(!h.r.calls.some((c) => c.method === 'PATCH'), 'with no sandbox, live keeps deploying every merge — work always has somewhere to land');
   assert.deepEqual(h.intentWrites, [44], 'the key is cleared');
 });
 
@@ -210,7 +218,7 @@ await ta('an app already live adds its sandbox: the live app is not created, rea
   const h = harness({ host: { postgresId: 'dpg-new', serviceId: 'srv-live0001', state: 'live', sandbox: { state: 'requested' } } });
   const out = await h.run();
   assert.equal(out.ok, true, out.error);
-  assert.deepEqual(writesTo(h.r.calls), ['POST /services'], 'one write: the sandbox');
+  assert.deepEqual(writesTo(h.r.calls), ['POST /services', 'PATCH /services/srv-live0001'], 'the sandbox, then live switched to manual deploys — never redeployed');
   assert.ok(created(h, 'demo-sandbox'));
   assert.equal(h.inst.app_host.state, 'live', 'the app stays live — not knocked back to building');
   assert.equal(h.inst.app_host.sandbox.state, 'deploying');

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);