@bongos/core 1.25.20 → 1.25.22

package/scripts/bongos/government-walk.js

@@ -49,6 +49,7 @@
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
+const { decidedOf, adoptedByFiling, soleMemberRows } = require('./government-walk-sole'); // task 1005130: a board of one decides by filing
 
 const ROOT = path.resolve(__dirname, '..', '..');
 const DOC_PATH = path.join(ROOT, 'docs', 'governance', 'government-walk.md');
@@ -262,9 +263,9 @@ function makeStore(catalog) {
       }
       return item.opened_by ?? null;
     },
-    async insertBoardVote({ itemId, voterId, direction, reasonMd = null, sectionKey = null }) {
+    async insertBoardVote({ itemId, voterId, direction, reasonMd = null, sectionKey = null, castVia = 'ballot' }) {
       if (s.votes.some((v) => v.item_id === String(itemId) && v.voter_id === String(voterId))) return null;
-      const row = { id: next(), item_id: String(itemId), voter_id: String(voterId), direction, reason_md: reasonMd, section_key: sectionKey, cast_at: tick() };
+      const row = { id: next(), item_id: String(itemId), voter_id: String(voterId), direction, reason_md: reasonMd, section_key: sectionKey, cast_via: castVia, cast_at: tick() };
       s.votes.push(row);
       return copy(row);
     },
@@ -774,20 +775,17 @@ async function runWalk() {
     return { got: `${r.status}, stage ${stage}`, pass: r.status === 200 && stage === 'decide' };
   });
   let charterItem = null;
-  await check(`Deciding with ${CHOSEN} saves the plan and files the pick as a charter amendment`, 'plan saved, charter sitting, one vote decides', async () => {
+  await check(`Deciding with ${CHOSEN} saves the plan and files the pick as a charter amendment`, 'plan saved, charter adopted', async () => {
     const r = await call(FOUNDER, 'POST', '/founding/plan', { government: CHOSEN });
     const c = (r.json && r.json.charter) || {};
     charterItem = c.item_id || null;
-    return { got: `${r.status}, charter ${c.state}, one vote decides ${c.one_vote_decides}`, pass: r.status === 200 && c.state === 'sitting' && c.one_vote_decides === true };
+    return { got: `${r.status}, charter ${c.state}`, pass: r.status === 200 && c.state === 'adopted' && !!charterItem };
   });
   await check('Saving the plan moved the project to its first stage', 'stage scope', async () => {
     const g = await genesis.readGenesis();
     return { got: `stage ${g && g.stage}`, pass: !!g && g.stage === 'scope' };
   });
-  await check('The founder\'s one yes ratifies the pick under the Monarchy it is born with', 'passed', async () => {
-    const r = await vote(FOUNDER, charterItem);
-    return { got: `${r.status} ${r.json && r.json.outcome}`, pass: r.status === 201 && r.json.outcome === 'passed' };
-  });
+  await check('The founder\'s one yes ratifies the pick under the Monarchy it is born with: as its only member, choosing it was that yes', 'passed; the founder\'s yes, cast by filing', async () => adoptedByFiling({ store, stateOf, itemId: charterItem, voterId: FOUNDER }));
   await check('The constitution now reads as the government chosen at decide', `reads as ${CHOSEN}, no divergence`, async () => {
     const c = await constitution();
     const f = c && c.charter && c.charter.reads_as && c.charter.reads_as.form;
@@ -928,8 +926,8 @@ async function runWalk() {
     const r = await call(FOUNDER, 'POST', '/government/board/decision-rules', { rules });
     const itemId = r.json && r.json.item && r.json.item.id;
     if (r.status !== 201 || !itemId) return { ok: false, why: `${r.status} ${code(r)}` };
-    const v = await vote(FOUNDER, itemId);
-    return { ok: v.status === 201 && v.json.outcome === 'passed', why: `vote ${v.status} ${v.json && v.json.outcome}` };
+    const d = decidedOf(r); // the founder is the Monarchy's only member, so filing it is their one yes
+    return { ok: d.closed === true && d.outcome === 'passed', why: `filed ${d.outcome || 'undecided'}` };
   }
   const rowOf = async (area) => {
     const c = await constitution();
@@ -1094,12 +1092,13 @@ async function walkNewMachinery({ call, code, vote, voteAll, check, section, sta
     const s = await positionsPort().lawsForSession();
     return { got: `${book.in_force} in force; ${s.inject ? 'a laws block' : 'no laws block'}`, pass: book.in_force === 0 && s.inject === false };
   });
-  await check('A law is proposed: filed as a laws amendment, and proposing writes nothing', '201, sitting open; still 0 in force', async () => {
-    const r = await call(FOUNDER_ID, 'POST', '/government/board/laws', { enact: [SHORT_LAW] });
+  await check('A law is proposed by a builder the board does not seat: filed as a laws amendment, and proposing writes nothing', '201, sitting open; still 0 in force', async () => {
+    const r = await call(BEN, 'POST', '/government/board/laws', { enact: [SHORT_LAW] });
     lawItem = itemIdOf(r);
     const book = await lawsInForce();
     return { got: `${r.status}, sitting ${stateOf(lawItem)}; still ${book.in_force} in force`, pass: r.status === 201 && stateOf(lawItem) === 'open' && book.in_force === 0 };
   });
+  await soleMemberRows({ check, call, vote, code, store, stateOf, itemIdOf, ids: { EVE, BEN, FOUNDER_ID }, SHORT_LAW });
   await check('Someone the board does not seat cannot pass it', '403 not_board_member', async () => {
     const r = await vote(BEN, lawItem);
     return { got: `${r.status} ${code(r)}`, pass: r.status === 403 && code(r) === 'not_board_member' };
@@ -1134,9 +1133,9 @@ async function walkNewMachinery({ call, code, vote, voteAll, check, section, sta
     const r = await call(BEN, 'PATCH', '/me/interaction', { verbosity: 'concise' });
     return { got: `${r.status}`, pass: r.status === 200 };
   });
-  await check('Repealed by a vote, the law leaves every session and unlocks the setting', 'passed; 0 in force; no laws block; 200', async () => {
+  await check('Repealed by the founder, the board\'s only member, whose filing is their one yes: the law leaves every session and unlocks the setting', 'passed; 0 in force; no laws block; 200', async () => {
     const r = await call(FOUNDER_ID, 'POST', '/government/board/laws', { repeal: [lawId] });
-    const v = await vote(FOUNDER_ID, itemIdOf(r));
+    const v = { json: { outcome: decidedOf(r).outcome } };
     const book = await lawsInForce();
     const s = await positionsPort().lawsForSession();
     const w = await call(BEN, 'PATCH', '/me/interaction', { verbosity: 'detailed' });
@@ -1152,7 +1151,7 @@ async function walkNewMachinery({ call, code, vote, voteAll, check, section, sta
     await check(`Strictness: ${from} to ${key} is one vote, and its locks bite`, `one sitting; passed; ${key} in force; exploratory wandering ${wander}`, async () => {
       const r = await call(FOUNDER_ID, 'POST', '/government/board/presets', { preset: key });
       const id = itemIdOf(r);
-      const v = await vote(FOUNDER_ID, id);
+      const v = { json: { outcome: decidedOf(r).outcome } }; // the only member's filing is their one yes
       const p = await presetNow();
       const w = await call(BEN, 'PATCH', '/me/wandering', { wandering: 3 });
       const ws = `${w.status}${w.status === 200 ? '' : ` ${code(w)}`}`;
@@ -1162,7 +1161,7 @@ async function walkNewMachinery({ call, code, vote, voteAll, check, section, sta
   await check('Every preset law is repealed by one more vote, so the book ends empty', 'passed; 0 in force; no preset', async () => {
     const ids = ((await lawsInForce()).laws || []).map((l) => l.id);
     const r = await call(FOUNDER_ID, 'POST', '/government/board/laws', { repeal: ids });
-    const v = await vote(FOUNDER_ID, itemIdOf(r));
+    const v = { json: { outcome: decidedOf(r).outcome } }; // the only member's filing is their one yes
     const book = await lawsInForce();
     const p = await presetNow();
     return { got: `${v.json && v.json.outcome}; ${book.in_force} in force; ${p.current ? `${p.current} in force` : 'no preset'}`, pass: book.in_force === 0 && p.current == null };

package/scripts/bongos/init.js

@@ -545,6 +545,19 @@ function buildReadme(branding = {}) {
     '',
     'Requires Node >= 22 and Postgres installed locally (macOS/Linux; on Windows use WSL). If anything looks off, `bongos doctor` checks your setup and prints the fix.',
     '',
+    // The project's sandbox (task 1005291, ADR 0406 §5): the one line that makes the app
+    // behave safely when it runs as its sandbox copy, and nothing at all on the live site.
+    "## Your app's sandbox",
+    '',
+    "If your app runs on Render, Bongos also runs a free sandbox copy of it that takes every finished change first. Put this at the top of a Node app so the sandbox only reads from payment, email and messaging providers, and shows a \"Sandbox\" band on every page:",
+    '',
+    '```js',
+    "const sandbox = require('@bongos/core/sandbox').install(); // does nothing on the live site",
+    'app.use(sandbox.middleware); // Express-style apps: the band, and /__bongos/sandbox',
+    '```',
+    '',
+    'Seed test data when `BONGOS_SANDBOX=1`, and give the sandbox test keys. If you lend a real key, lend a read-only one.',
+    '',
     '## Where to look next',
     '',
     '- `CLAUDE.md` — how this project is built (the operating manual agents read first).',

package/scripts/bongos/package-core.js

@@ -330,6 +330,8 @@ function buildPackageJson({ version, sourceDeps, sourceOverrides }) {
       './bongos/api-path-404': './src/bongos/api-path-404.js',
       './module-loader/loader': './src/module-loader/loader.js',
       './modules': './src/modules.js',
+      // A project's app loads this to behave as its sandbox (task 1005291, ADR 0406 §5).
+      './sandbox': './src/sandbox/index.js',
       './module-seams': './src/module-seams.js',
     },
     engines: { node: '>=22' },

package/scripts/bongos/provision-render-common.js

@@ -0,0 +1,48 @@
+'use strict';
+// provision-render-common.js — the pieces every Render runner leg shares: the client for a
+// lent key, the one app_host writer, clearing the key, and an owner-readable reason
+// (task 1005290; first written in provision-render.js by task 1004183).
+//
+// WHY ITS OWN FILE. The standup leg (provision-render.js), the sandbox leg
+// (provision-render-sandbox.js) and the promote leg (provision-render-promote.js) all
+// need these. Kept in the standup file, the sandbox leg reaching back for them made a
+// require cycle (the standup file requires the sandbox file), which the fitness ratchet
+// rightly refuses. Here, every leg depends on this file and on nothing of each other's.
+
+const { RenderApi } = require('./render-api.js');
+
+// A key waiting longer than this was lent for a run that never came. It is refused and
+// cleared rather than spent late.
+const KEY_TTL_MS = 30 * 60 * 1000;
+
+function renderApiFor(deps, token, ownerId) {
+  if (deps.renderApiFactory) return deps.renderApiFactory({ token, ownerId });
+  return new RenderApi({ token, ownerId, dryRun: !deps.apply, fetchImpl: deps.fetchImpl, log: deps.log });
+}
+
+// Merge `patch` into the row's app_host. The runner is the only writer while an intent
+// runs, and the web tier only writes it when enqueuing, which the open-intent index
+// serialises — so a merge needs no read-modify-write.
+async function recordAppHost(db, instId, patch) {
+  await db.query(
+    `UPDATE provisioning_instances SET app_host = COALESCE(app_host, '{}'::jsonb) || $2::jsonb WHERE id = $1`,
+    [instId, JSON.stringify({ ...patch, updatedAt: new Date().toISOString() })]);
+}
+
+async function clearBorrowedKey(db, intentId) {
+  await db.query(`UPDATE provisioning_intents SET borrowed_key_enc = NULL WHERE id = $1`, [intentId]);
+}
+
+// The owner reads this reason on the setup screen (app-status.js oneSentence). A refusal
+// from Render's API used to arrive as its raw line — "Render POST /services failed: …" —
+// so an answer from Render is re-said as a sentence with Render's own reason kept whole
+// (task 1004464). Anything else is already the leg's own words.
+function plainReason(e) {
+  const msg = e && e.message ? e.message : String(e);
+  const said = e && e.status != null && e.body && typeof e.body.message === 'string' ? e.body.message.trim() : '';
+  if (said) return `Render would not set up the app: ${said}`;
+  const m = /^Render (?:GET|POST|PATCH|PUT|DELETE) \S+ failed: ([\s\S]+)$/.exec(msg);
+  return m ? `Render would not set up the app: ${m[1].trim()}` : msg;
+}
+
+module.exports = { KEY_TTL_MS, renderApiFor, recordAppHost, clearBorrowedKey, plainReason };

package/scripts/bongos/provision-render-promote.js

@@ -0,0 +1,93 @@
+'use strict';
+// provision-render-promote.js — a person promotes what ran on the sandbox to the live app:
+// the runner half of the `render-promote` intent (task 1005290; ADR 0406 §2, ADR 0327).
+//
+// WHY. Once a project has a sandbox, finished work lands on the sandbox only (it follows
+// `main`), and the live Render service no longer deploys on every merge. The live app
+// moves only here, when a person pressed promote and lent their Render key for that one
+// action. That is the project law "Land only. Ask before going live" made physical: no
+// ship, in Auto or Manual mode, reaches this file; only an owner's press does.
+//
+// WHAT IT DOES, in order, and why the order matters:
+//   1. checks the chosen change RAN on the sandbox (it is one of the sandbox's own deploys
+//      that went live there), and that the live app still runs what the owner was shown;
+//   2. RECORDS the promotion (provisioning_promotions) — before anything is sent, so
+//      nothing reaches the live app through Bongos without a row saying who and what;
+//   3. switches the live service to manual deploys (idempotent), so the next merge cannot
+//      reach it by itself;
+//   4. asks Render to deploy exactly that commit to the live service.
+//
+// Like the standup leg: the key is decrypted here, used for this run, and cleared in a
+// `finally`; every failure is terminal (the owner presses again with the key); every call
+// goes through scripts/bongos/render-api.js, which pins the workspace.
+
+const COMMIT_RE = /^[0-9a-f]{7,40}$/;
+// Only a deploy that served on the sandbox can be promoted: one still building, or one
+// whose build failed, never ran there for anyone to look at.
+const SERVED = ['live', 'deactivated'];
+
+const commitOf = (d) => (d && d.commit && d.commit.id) || null;
+
+async function promoteInstance(inst, deps, intent) {
+  const { db, log } = deps;
+  const render = require('./provision-render-common.js');
+  const secretBox = deps.secretBox || require('../../src/bongos/secret-box');
+  const host = inst.app_host || {};
+  const ask = host.promote || {};
+  let promotionId = null;
+  try {
+    if (!intent || !intent.borrowed_key_enc) return await refuse('no Render key came with the promotion — press promote again');
+    const age = Date.now() - new Date(intent.created_at || 0).getTime();
+    if (!(age < render.KEY_TTL_MS)) return await refuse('the Render key waited too long to be used and was cleared — press promote again');
+    if (host.platform !== 'render' || !host.serviceId || !host.ownerId) return await refuse('this project has no app on Render to promote to');
+    const sb = host.sandbox || {};
+    if (!sb.serviceId) return await refuse('this project has no sandbox to promote from');
+    if (!COMMIT_RE.test(String(ask.commitId || ''))) return await refuse('no change was chosen to promote');
+
+    const api = render.renderApiFor(deps, secretBox.decrypt(intent.borrowed_key_enc), host.ownerId);
+    const owners = await api.listOwners();
+    if (!owners.some((o) => o.id === host.ownerId)) return await refuse(`this Render key cannot reach workspace ${host.ownerId}`);
+
+    // 1. it ran on the sandbox, and live is what the owner was shown
+    const sandboxDeploys = await api.listDeploys(sb.serviceId, { limit: 50 });
+    const ran = sandboxDeploys.find((d) => commitOf(d) === ask.commitId && SERVED.includes(d.status));
+    if (!ran) return await refuse('that change has not run on the sandbox, so it cannot be promoted');
+    const liveDeploys = await api.listDeploys(host.serviceId, { limit: 10 });
+    const liveCommit = commitOf(liveDeploys.find((d) => d.status === 'live'));
+    if ((ask.expectLiveCommit || null) !== liveCommit) return await refuse('what your live app runs changed since you looked, so nothing was done — look again and promote');
+    if (liveCommit === ask.commitId) return await refuse('that change is already on your live app');
+
+    // 2. the record comes first
+    const message = String((ran.commit && ran.commit.message) || '').split('\n')[0].slice(0, 300);
+    const { rows } = await db.query(
+      `INSERT INTO provisioning_promotions (instance_id, commit_id, commit_message, from_commit_id, sandbox_deploy_id, requested_by, state)
+       VALUES ($1, $2, $3, $4, $5, $6, 'started') RETURNING id`,
+      [inst.id, ask.commitId, message, liveCommit, ran.id || null, ask.requestedBy == null ? null : String(ask.requestedBy)]);
+    promotionId = rows && rows[0] ? rows[0].id : null;
+
+    // 3. live stops following main, so only promotions move it
+    await api.setAutoDeploy(host.serviceId, false);
+    // 4. exactly that commit
+    const dep = await api.triggerDeploy(host.serviceId, { commitId: ask.commitId });
+    const deployId = (dep && dep.id) || null;
+    await db.query(`UPDATE provisioning_promotions SET state = 'sent', render_deploy_id = $2, updated_at = now() WHERE id = $1`, [promotionId, deployId]);
+    await render.recordAppHost(db, inst.id, { liveAutoDeploy: 'off', promote: { ...ask, state: 'sent', error: null, renderDeployId: deployId } });
+    log(`  [render] ${inst.slug}: promoted ${ask.commitId.slice(0, 7)} from the sandbox to the live app (deploy ${deployId || 'started'})`);
+    return { ok: true };
+  } catch (e) {
+    return await refuse(render.plainReason(e).replace(/^Render would not set up the app/, 'Render would not promote it'));
+  } finally {
+    if (intent && intent.id != null) await render.clearBorrowedKey(db, intent.id);
+  }
+
+  async function refuse(error) {
+    if (promotionId != null) {
+      await db.query(`UPDATE provisioning_promotions SET state = 'failed', error = $2, updated_at = now() WHERE id = $1`, [promotionId, error]).catch(() => {});
+    }
+    await render.recordAppHost(db, inst.id, { promote: { ...ask, state: 'failed', error } }).catch(() => {});
+    log(`  ✖ [render] ${inst.slug} promote: ${error}`);
+    return { ok: false, terminal: true, error };
+  }
+}
+
+module.exports = { promoteInstance, COMMIT_RE };

package/scripts/bongos/provision-render-sandbox.js

@@ -20,14 +20,15 @@
 //   3. SERVICE — a free web service named `<slug>-sandbox`, auto-deploying from `main`,
 //      with BONGOS_SANDBOX=1. Found by name first, so a re-run never makes a second one.
 //
-// The live service is not touched here: switching it to manual deploys belongs with the
-// promote button that replaces them (task 1005290).
+// Once the sandbox stands, the LIVE service is switched to manual deploys, so only a
+// person's promotion moves it (task 1005290; scripts/bongos/provision-render-promote.js).
 //
 // TEARDOWN removes the sandbox service and the sandbox database only — never the live app
 // or its data (ADR 0406 §7). It needs the owner's key; without one the sandbox is
 // forgotten and the owner is told exactly what to delete.
 
 const payload = require('./render-payload.js');
+const { recordAppHost } = require('./provision-render-common.js');
 const { parseTargetRef } = require('./provision-repo-auth.js');
 
 async function recordSandbox(db, instId, patch) {
@@ -111,15 +112,30 @@ async function standupSandbox(api, inst, host, deps) {
     let svc = sb.serviceId ? await api.getService(sb.serviceId).catch(() => null) : null;
     if (!svc) svc = await api.findServiceByName(name);
     if (!svc) {
+      // The sandbox page's key (task 1005291): kept on the row, which only the owner's
+      // project page reads, and set on the sandbox, which checks it.
+      const pageToken = require('node:crypto').randomBytes(24).toString('hex');
       const created = await api.createService(payload.sandboxServicePayload(inst, {
         ownerId: api.ownerId, repoUrl: `https://github.com/${repo.owner}/${repo.name}`, region, build,
-        dbUrl: dbStage.state === 'ready' ? dbStage.url : null,
+        dbUrl: dbStage.state === 'ready' ? dbStage.url : null, pageToken,
       }));
+      await recordSandbox(db, inst.id, { pageKey: pageToken });
       svc = created.service;
       log(`  [render] created sandbox service ${svc.id} (free, follows main)`);
     }
     const url = (svc.serviceDetails && svc.serviceDetails.url) || null;
     await recordSandbox(db, inst.id, { state: 'deploying', serviceId: svc.id, serviceUrl: url, error: null });
+    // From here on finished work reaches the sandbox only: the live service stops deploying
+    // on every merge, and moves when a person promotes (task 1005290, ADR 0406 §2). Only once
+    // the sandbox exists, so live is never left with nowhere for work to land. A failure is
+    // said on the row and the sandbox stands; the next promotion switches it again.
+    try {
+      await api.setAutoDeploy(host.serviceId, false);
+      await recordAppHost(db, inst.id, { liveAutoDeploy: 'off' }); // the one app_host writer
+      log('  [render] the live app now moves only when a person promotes');
+    } catch (e) {
+      log(`  (the live app still deploys every merge: ${e && e.message})`);
+    }
     return { ok: true };
   } catch (e) {
     const error = `The sandbox could not be set up: ${String((e && e.message) || e).split('\n')[0].slice(0, 240)}`;

package/scripts/bongos/provision-render.js

@@ -31,32 +31,12 @@
 // Every Render call goes through scripts/bongos/render-api.js, which pins the workspace and
 // asserts it on every response, and which cannot delete.
 
-const { RenderApi } = require('./render-api.js');
 const payload = require('./render-payload.js');
 const { parseTargetRef } = require('./provision-repo-auth.js');
 const sandbox = require('./provision-render-sandbox.js');
-
-// A key waiting longer than this was lent for a run that never came. It is refused and
-// cleared rather than spent late.
-const KEY_TTL_MS = 30 * 60 * 1000;
-
-function renderApiFor(deps, token, ownerId) {
-  if (deps.renderApiFactory) return deps.renderApiFactory({ token, ownerId });
-  return new RenderApi({ token, ownerId, dryRun: !deps.apply, fetchImpl: deps.fetchImpl, log: deps.log });
-}
-
-// Merge `patch` into the row's app_host. The runner is the only writer while an intent
-// runs, and the web tier only writes it when enqueuing, which the open-intent index
-// serialises — so a merge needs no read-modify-write.
-async function recordAppHost(db, instId, patch) {
-  await db.query(
-    `UPDATE provisioning_instances SET app_host = COALESCE(app_host, '{}'::jsonb) || $2::jsonb WHERE id = $1`,
-    [instId, JSON.stringify({ ...patch, updatedAt: new Date().toISOString() })]);
-}
-
-async function clearBorrowedKey(db, intentId) {
-  await db.query(`UPDATE provisioning_intents SET borrowed_key_enc = NULL WHERE id = $1`, [intentId]);
-}
+// The pieces every Render leg shares live in their own file, so the sandbox and promote
+// legs can use them without a require cycle back into this one (task 1005290).
+const { KEY_TTL_MS, renderApiFor, recordAppHost, clearBorrowedKey, plainReason } = require('./provision-render-common.js');
 
 // Whether a Render service's repository is this project's. Render reports it as a URL;
 // compared as owner/name, case-insensitively, the way GitHub resolves them.
@@ -118,18 +98,6 @@ async function greenfield(api, inst, host, deps) {
   return { ok: true };
 }
 
-// The owner reads this reason on the setup screen (app-status.js oneSentence). A refusal
-// from Render's API used to arrive as its raw line — "Render POST /services failed: …" —
-// so an answer from Render is re-said as a sentence with Render's own reason kept whole
-// (task 1004464). Anything else is already the leg's own words.
-function plainReason(e) {
-  const msg = e && e.message ? e.message : String(e);
-  const said = e && e.status != null && e.body && typeof e.body.message === 'string' ? e.body.message.trim() : '';
-  if (said) return `Render would not set up the app: ${said}`;
-  const m = /^Render (?:GET|POST|PATCH|PUT|DELETE) \S+ failed: ([\s\S]+)$/.exec(msg);
-  return m ? `Render would not set up the app: ${m[1].trim()}` : msg;
-}
-
 async function renderStandupInstance(inst, deps, intent) {
   const { db, log } = deps;
   const secretBox = deps.secretBox || require('../../src/bongos/secret-box');
@@ -233,4 +201,4 @@ async function forgetRenderApp(inst, deps) {
   if (apply) await recordAppHost(db, inst.id, { state: 'disconnected' });
 }
 
-module.exports = { renderStandupInstance, afterProvision, forgetRenderApp, clearBorrowedKey, recordAppHost, KEY_TTL_MS };
+module.exports = { renderStandupInstance, afterProvision, forgetRenderApp, clearBorrowedKey, recordAppHost, renderApiFor, plainReason, KEY_TTL_MS };

package/scripts/bongos/provision.js

@@ -1255,6 +1255,7 @@ async function cmdRunIntents(deps) {
       else if (intent.action === 'core-upgrade') result = await coreUpgradeInstance(inst, deps, intent); // also reads the INTENT: the version the owner previewed (ADR 0293 D4)
       else if (intent.action === 'core-upgrade-preflight') result = await preflightCoreUpgrade(inst, deps, intent); // changes nothing; caches what the move WOULD say (task 1004121)
       else if (intent.action === 'repo-private' || intent.action === 'render-standup') result = intent.action === 'repo-private' ? await require('./provision-repo-private.js').repoPrivateInstance(inst, deps) : await require('./provision-render.js').renderStandupInstance(inst, deps, intent); // wire the deploy key, THEN flip (task 1004193) · spend the borrowed Render key once (task 1004183); required here — this file is at the size ratchet
+      else if (intent.action === 'render-promote') result = await require('./provision-render-promote.js').promoteInstance(inst, deps, intent); // a person's promotion of a sandbox change to the live app (task 1005290, ADR 0406)
       else result = { ok: false, error: `unknown_action '${intent.action}' — runner core ${coreVersionSafe() || '?'} does not know it (runner too old?); refusing to guess` };
       if (result && result.ok === false) {
         // WAIT OR RETIRE (task 1004447, intent-retry.js): a transient failure waits ~15m/1h/6h; a

package/scripts/bongos/render-api.js

@@ -163,9 +163,24 @@ class RenderApi extends JsonHttpApi {
     return super._req('DELETE', path, null);
   }
 
-  async triggerDeploy(serviceId) {
+  // Start a deploy. With `commitId` Render builds THAT commit rather than the branch's
+  // newest — how a promotion moves the live app to exactly what ran on the sandbox (ADR
+  // 0406 §2, task 1005290). The answer carries no owner, so the service is read first.
+  async triggerDeploy(serviceId, { commitId } = {}) {
     await this.getService(serviceId);
-    return this._req('POST', `/services/${encodeURIComponent(serviceId)}/deploys`, {}, { dryRunResult: { id: null } });
+    const body = commitId ? { commitId } : {};
+    return this._req('POST', `/services/${encodeURIComponent(serviceId)}/deploys`, body, { dryRunResult: { id: null } });
+  }
+
+  // Whether the service deploys on every push to its branch. The live app is switched to
+  // `no` once its project has a sandbox, so only a person's promotion moves it (ADR 0406
+  // §2, task 1005290). A write to the owner's service, through the guard, nothing else.
+  async setAutoDeploy(serviceId, on) {
+    await this.getService(serviceId);
+    const json = await this._req('PATCH', `/services/${encodeURIComponent(serviceId)}`, { autoDeploy: on ? 'yes' : 'no' }, {
+      dryRunResult: { id: serviceId, ownerId: this.ownerId, autoDeploy: on ? 'yes' : 'no' },
+    });
+    return this.assertOwned(json && json.service ? json.service : json, `service ${serviceId}`);
   }
 
   // A service's deploys, newest first, as the bare deploy objects (Render wraps each in

package/scripts/bongos/render-payload.js

@@ -87,11 +87,14 @@ function renderServicePayload(inst, { ownerId, repoUrl, branch, webPlan, region,
 // with BONGOS_SANDBOX=1 so the app (and the starter's outbound gate, task 1005291) knows
 // it is not the live site. `dbUrl` is the sandbox's OWN database, never the live one.
 const SANDBOX_SUFFIX = 'sandbox';
-function sandboxServicePayload(inst, { ownerId, repoUrl, region, build, dbUrl }) {
+// `pageToken` is the sandbox's own page key: its /__bongos/sandbox shows what was refused
+// and which real keys are lent only to a visitor who carries it (the owner, via their
+// owner-only project page). Not a credential to anything else (task 1005291).
+function sandboxServicePayload(inst, { ownerId, repoUrl, region, build, dbUrl, pageToken }) {
   const p = renderServicePayload(inst, { ownerId, repoUrl, branch: 'main', webPlan: 'free', region, build, dbUrl });
   p.name = resourceName(inst, SANDBOX_SUFFIX);
   p.autoDeploy = 'yes';
-  p.envVars = [{ key: 'BONGOS_SANDBOX', value: '1' }, ...p.envVars];
+  p.envVars = [{ key: 'BONGOS_SANDBOX', value: '1' }, ...(pageToken ? [{ key: 'BONGOS_SANDBOX_PAGE_KEY', value: pageToken }] : []), ...p.envVars];
   return p;
 }
 

package/scripts/gds/government-walk-sole.js

@@ -0,0 +1,6 @@
+// scripts/gds/government-walk-sole.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/government-walk-sole.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'government-walk-sole.js');

package/scripts/gds/provision-render-common.js

@@ -0,0 +1,6 @@
+// scripts/gds/provision-render-common.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-render-common.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'provision-render-common.js');

package/scripts/gds/provision-render-promote.js

@@ -0,0 +1,6 @@
+// scripts/gds/provision-render-promote.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/provision-render-promote.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'provision-render-promote.js');