@bongos/core 1.25.16 → 1.25.18

package/modules/onboarding/genesis-work.js

@@ -41,7 +41,8 @@
 //
 // WHICH STAGES. A stage adopts the pattern by declaring its questions in QUESTIONS.
 // Strategize does (task 1005116); scope's guided door is its project interview (task 1005114);
-// charter, legalize and legislation adopt it when they are next touched. A stage with
+// charter asks how decisions should go and the founder's principles (task 1005119);
+// legalize and legislation adopt it when they are next touched. A stage with
 // no questions still takes a free page and a link.
 //
 // THE BOUNDARY. Pure apart from the store. The store is injected (tests) or the
@@ -57,6 +58,9 @@ const STATES = Object.freeze(['answered', 'not_sure', 'skipped']);
 const ORIGINS = Object.freeze(['founder', 'assisted', 'carried_over']);
 const LIMITS = Object.freeze({ answer: 4000, page: 20000, link: 500 });
 
+// A closed question's options: [key, label] pairs, frozen.
+const choices = (pairs) => Object.freeze(pairs.map(([key, label]) => Object.freeze({ key, label })));
+
 // Each adopted stage's questions, in the order the guided door asks them. `id` is
 // stable: a stored answer names it, so never rename or reuse one. `hint` is the shape
 // of a good answer, shown under the question in every door. `group` (optional) is a
@@ -83,6 +87,47 @@ const QUESTIONS = Object.freeze({
     Object.freeze({ id: 'others_wrong', group: 'The bet', ask: 'What is everyone else in this area getting wrong?',
       hint: 'The thing you believe that others in this space do not. This is the bet the project makes.' }),
   ]),
+  // CHARTER (task 1005119): how decisions should go, then the founder's principles.
+  // A question with `choices` is a CLOSED one: an answer is one of its keys, because
+  // the government module's recommender reads it (recommendations.js CHARTER_ANSWERS
+  // and presets.js PRINCIPLE_ANSWERS hold the same keys, by test; a module may not
+  // import a sibling, ADR 0083). The prose ones shape the drafted bylaws and code of
+  // conduct in the founder's own words. Every one is skippable and "not sure yet".
+  charter: Object.freeze([
+    Object.freeze({ id: 'final_say', group: 'How decisions go', ask: 'When people disagree, who should have the final say?',
+      hint: 'Who settles it in the end. This is who gets a vote.',
+      choices: choices([['founder', 'Me, the founder'], ['trusted', 'The people who have earned trust by shipping'],
+        ['everyone', 'Everyone on the project'], ['council', 'A small group I appoint']]) }),
+    Object.freeze({ id: 'agreement', group: 'How decisions go', ask: 'How much agreement should a decision need?',
+      hint: 'Fewer means faster; more means everyone is bought in.',
+      choices: choices([['first_ratifier', 'One yes is enough'], ['consent', 'It passes unless someone objects'],
+        ['majority', 'More than half must say yes'], ['unanimous', 'Everyone who votes must agree']]) }),
+    Object.freeze({ id: 'strangers', group: 'How decisions go', ask: 'Do you expect people you have not met to show up and contribute?',
+      hint: 'Whether newcomers should get a say straight away or earn it first.',
+      choices: choices([['yes', 'Yes'], ['no', 'No, it is people I know']]) }),
+    Object.freeze({ id: 'answers_to', group: 'How decisions go', ask: 'Is there anyone outside the project it answers to: funders, a mission, a legal entity?',
+      hint: 'Something the project must stay true to, whoever is building it.',
+      choices: choices([['yes', 'Yes'], ['no', 'No']]) }),
+    Object.freeze({ id: 'step_back', group: 'How decisions go', ask: 'Do you want to be able to step back later and hand this over?',
+      hint: 'Whether the project should keep deciding well without you.',
+      choices: choices([['yes', 'Yes'], ['no', 'No, I plan to stay at the helm']]) }),
+    Object.freeze({ id: 'speed', group: 'How decisions go', ask: 'Would you rather decide fast, or have everyone bought in?',
+      hint: 'When the two pull apart, which wins.',
+      choices: choices([['fast', 'Decide fast'], ['bought_in', 'Everyone bought in']]) }),
+    Object.freeze({ id: 'trust_level', group: 'Principles', ask: 'How much should people be trusted to work without checking in first?',
+      hint: 'This shapes how strict the rules for the project\'s AI agents are.',
+      choices: choices([['a_lot', 'A lot: let them get on with it'], ['some', 'Some: a few rules everyone follows'],
+        ['little', 'Little: tight rules, checked often']]) }),
+    Object.freeze({ id: 'catch_or_fix', group: 'Principles', ask: 'When something goes wrong, would you rather have caught it early, or move fast and fix it?',
+      hint: 'Neither is wrong. It sets how much is checked before work goes ahead.',
+      choices: choices([['catch_early', 'Catch it early'], ['move_fast', 'Move fast and fix it']]) }),
+    Object.freeze({ id: 'leave_behaviour', group: 'Principles', ask: 'What behaviour would make you ask someone to leave?',
+      hint: 'The line nobody crosses. It becomes the heart of the code of conduct.' }),
+    Object.freeze({ id: 'feel', group: 'Principles', ask: 'What do you want this project to feel like to work on?',
+      hint: 'A few words: calm, fast, careful, playful, serious.' }),
+    Object.freeze({ id: 'write_down', group: 'Principles', ask: 'Is there anything you want written down now, so it is not argued about later?',
+      hint: 'A rule, a promise or a boundary. It goes into the bylaws as you wrote it.' }),
+  ]),
   strategize: Object.freeze([
     Object.freeze({ id: 'big_pieces', ask: 'What are the big pieces, and in what order do they get built?',
       hint: 'Three to six pieces is plenty. Say why that order: what has to exist before what.' }),
@@ -116,6 +161,14 @@ function checkAnswer(stage, questionId, body = {}) {
   const words = text(b.text);
   if (words.length > LIMITS.answer) return { ok: false, reason: 'answer_too_long' };
   if (state === 'answered' && !words) return { ok: false, reason: 'empty_answer' };
+  // A closed question's answer is one of its keys (or its label, read back as the key),
+  // so the recommender reading it never has to guess at prose.
+  const q = questionFor(stage, questionId);
+  if (state === 'answered' && q.choices) {
+    const hit = q.choices.find((c) => c.key === words || c.label.toLowerCase() === words.toLowerCase());
+    if (!hit) return { ok: false, reason: 'not_a_choice', expected: q.choices.map((c) => c.key) };
+    return { ok: true, value: { state, answer_md: hit.key, origin } };
+  }
   return { ok: true, value: { state, answer_md: words || null, origin } };
 }
 
@@ -130,6 +183,7 @@ function checkLink(url) {
 
 // ── pure: the view ────────────────────────────────────────────────────────────
 
+const labelOf = (q, key) => { const c = (q.choices || []).find((x) => x.key === key); return c ? c.label : null; };
 const iso = (v) => (v ? new Date(v).toISOString() : null);
 
 // shapeStage(stage, work, answers) → one stage's record as every door sees it.
@@ -141,8 +195,11 @@ function shapeStage(stage, work, answers = []) {
     const a = byId.get(q.id);
     return {
       id: q.id, ask: q.ask, hint: q.hint, group: q.group || null,
+      choices: q.choices || null,
       answer: a ? {
         state: a.state, text: a.answer_md || null, origin: a.origin,
+        // a closed answer's words, for a reader who should not see the key
+        choice_label: q.choices && a.state === 'answered' ? labelOf(q, a.answer_md) : null,
         // A carried-over answer is shown as such until the founder makes it theirs.
         carried_over: a.origin === 'carried_over',
         updated_at: iso(a.updated_at),
@@ -190,7 +247,7 @@ function contextMarkdown(stages) {
     out.push(`## ${s.stage[0].toUpperCase()}${s.stage.slice(1)}`);
     for (const q of said) {
       const a = q.answer;
-      const body = a.state === 'answered' ? a.text : `${STATE_WORDS[a.state]}${a.text ? ` — ${a.text}` : ''}`;
+      const body = a.state === 'answered' ? (a.choice_label || a.text) : `${STATE_WORDS[a.state]}${a.text ? ` — ${a.text}` : ''}`;
       out.push(`- **${q.ask}**${ORIGIN_WORDS[a.origin] || ''}\n  ${String(body).replace(/\n/g, '\n  ')}`);
     }
     if (s.page) out.push('', '**In the founder\'s own words:**', '', s.page);
@@ -223,7 +280,11 @@ function assistPrompt(stage) {
   ];
   if (qs.length) {
     lines.push('The questions (the id in brackets is what you record the answer under):');
-    qs.forEach((q, i) => lines.push(`${i + 1}. [${q.id}] ${q.ask} (${q.hint})`));
+    qs.forEach((q, i) => {
+      lines.push(`${i + 1}. [${q.id}] ${q.ask} (${q.hint})`);
+      // A closed question records one of its keys, never prose.
+      if (q.choices) lines.push(`   Record one of: ${q.choices.map((c) => `${c.key} (${c.label})`).join(' · ')}`);
+    });
     lines.push('');
   }
   lines.push('To see what I have already said:  npx bongos genesis show ' + stage);
@@ -316,7 +377,43 @@ async function readAll(deps = {}) {
 async function readStage(stage, deps = {}) {
   if (!isStage(stage)) return { ok: false, reason: 'unknown_stage' };
   const all = await readAll(deps);
-  return { ok: true, work: all.find((s) => s.stage === stage) };
+  const work = all.find((s) => s.stage === stage);
+  if (stage === 'charter') work.advice = await charterAdvice(work, deps);
+  return { ok: true, work };
+}
+
+// charterAdvice(work, deps) — THE CHARTER STAGE'S RECOMMENDATION (task 1005119): the
+// founder's answers, handed to the government module's one recommender through its
+// port. Closed answers go as their keys, prose ones as the founder's words; "not sure
+// yet" and skipped are not sent, so the recommender falls back to what it does
+// without them. The head count is the founder's own expected number from the plan
+// when they gave one. Null with no government module, and null (never a failed read)
+// if the advice cannot be built: the questions still work without it.
+async function charterAdvice(work, deps = {}) {
+  try {
+    const api = deps.api || require('../../src/module-api');
+    const gov = deps.government !== undefined ? deps.government : api.resolveOptional('government');
+    if (!gov || typeof gov.charterAdvice !== 'function') return null;
+    const answers = {};
+    const prose = {};
+    for (const q of work.questions) {
+      if (!q.answer || q.answer.state !== 'answered') continue;
+      (q.choices ? answers : prose)[q.id] = q.answer.text;
+    }
+    let headcount = null;
+    const get = deps.getSetting || (api.projectSettings && api.projectSettings.get);
+    if (get) {
+      const row = await get('founding.plan');
+      try {
+        const v = row && row.value;
+        const plan = typeof v === 'string' ? JSON.parse(v) : v;
+        headcount = (plan && plan.expected_builders) || null;
+      } catch (_) { headcount = null; }
+    }
+    return await gov.charterAdvice({ answers, prose, headcount });
+  } catch (_) {
+    return null;
+  }
 }
 
 async function setDoor(stage, door, by, deps = {}) {

package/modules/onboarding/routes/genesis-work.js

@@ -15,7 +15,7 @@ const work = require('../genesis-work');
 
 const REFUSALS = {
   unknown_stage: 404, unknown_question: 404, bad_door: 400, bad_state: 400, bad_origin: 400,
-  empty_answer: 400, answer_too_long: 400, page_too_long: 400, link_too_long: 400, bad_link: 400,
+  empty_answer: 400, not_a_choice: 400, answer_too_long: 400, page_too_long: 400, link_too_long: 400, bad_link: 400,
 };
 
 // `deps` is for tests only (an in-memory store); production passes none.
@@ -25,7 +25,7 @@ module.exports = function mountGenesisWorkRoutes(router, deps = {}) {
     try {
       const r = await fn(req);
       if (r && r.ok === false) {
-        return res.status(REFUSALS[r.reason] || 409).json({ error: { code: r.reason, message: r.reason } });
+        return res.status(REFUSALS[r.reason] || 409).json({ error: { code: r.reason, message: r.reason, ...(r.expected ? { expected: r.expected } : {}) } });
       }
       res.set('Cache-Control', 'no-store');
       res.json(r);

package/modules/platform-identity/module.json

@@ -12,7 +12,7 @@
   "maintainer": "Cloud Bongos maintainers",
   "maintenance": { "status": "core-maintained" },
   "contributes": {
-    "routes": ["sso", "sso-invites", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard", "guilds", "guilds-public"],
+    "routes": ["sso", "sso-invites", "sso-app-status", "projects", "my-projects", "scouting", "profile", "public-profile", "connections", "community-search", "community-leaderboard", "guilds", "guilds-public"],
     "migrations": true,
     "pollers": ["code-sweep", "visibility-pull", "guild-totals"]
   },

package/modules/platform-identity/routes/sso-app-status.js

@@ -0,0 +1,65 @@
+// modules/platform-identity/routes/sso-app-status.js — a hosted project asks the hub where
+// its own APP runs (task 1004571). Server-to-server, authenticated by client_id +
+// client_secret like the membership check-in and the invite notices; the asker is core's
+// readAppStatusFromHub (src/bongos/auth-admission.js), and its hall shows the answer in the
+// options menu.
+//
+//   POST /sso/app-status  { client_id, client_secret } → { ok, known, app, sandbox }
+//
+// A PROJECT READS ITS OWN ROW, NEVER ANOTHER'S. The project is the authenticated client
+// itself, named by both halves of the ADR 0246 projection (client_id = slug at the client's
+// registered origin) — nothing in the body can name a different one. The row and its
+// app-status reading belong to the provisioning module, so this asks through the
+// `provisioning.projectAppStatus` port; a hub without provisioning answers `known: false`.
+//
+// WHAT IT CARRIES is app-status.js's shape as is: the project is already trusted with its
+// own setup (it is the project's own hall asking). Its hall decides, per viewer, what an
+// owner sees beyond the state. Nothing here calls Render.
+//
+// WIRE SKEW (ADR 0352): a NEW route, so an older hub answers 404 and the hall says it could
+// not ask. The body is validated strictly, so a field added later must ride a header, or ship
+// on the hub and be released before any instance sends it.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const pi = require('../platform-identity');
+
+const log = api.logger('platform-identity');
+const { pool, validateOrRespond } = api;
+
+/** The host a client's registered origin names, lowercased; null for no usable origin. */
+function originHost(origin) {
+  try { return new URL(String(origin || '')).host.toLowerCase() || null; } catch { return null; }
+}
+
+module.exports = function ssoAppStatusRoutes({ resolvePort = (name) => api.resolveOptional(name), db = pool } = {}) {
+  const router = express.Router();
+
+  // rank: public — authenticated by client_id + client_secret, not a builder rank.
+  router.post('/sso/app-status', async (req, res) => {
+    if (validateOrRespond(req, res, {
+      client_id: { required: true, type: 'string', maxLength: 200 },
+      client_secret: { required: true, type: 'string', maxLength: 512 },
+    }, { strict: true })) return undefined;
+    const { client_id, client_secret } = req.body;
+    try {
+      const client = await pi.getClient(client_id, { pool: db });
+      if (!client || client.status !== 'active' || !pi.clientSecretValid(client, client_secret)) {
+        return res.fail('invalid_client', 401);
+      }
+      const read = resolvePort('provisioning.projectAppStatus');
+      const host = originHost(client.origin);
+      const found = typeof read === 'function' && host ? await read({ slug: client.client_id, host }) : null;
+      if (!found) return res.json({ ok: true, known: false, app: null, sandbox: null });
+      return res.json({ ok: true, known: true, app: found.app || null, sandbox: found.sandbox || null });
+    } catch (err) {
+      log.error('[platform-identity] /sso/app-status', err && err.message);
+      return res.fail('app_status_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  return router;
+};
+
+module.exports.originHost = originHost;

package/modules/provisioning/module.json

@@ -40,6 +40,7 @@
     "provisioning.projectOwnedBy",
     "provisioning.projectPublishIdentity",
     "provisioning.selfUpdateChannel",
+    "provisioning.projectAppStatus",
     "provisioning.moduleCatalog"
   ],
   "consumes": []

package/modules/provisioning/pollers/app-liveness.js

@@ -86,7 +86,29 @@ async function sweepOnce(deps = {}) {
       [r.id, h.state]);
     if (rowCount) { live++; log(`[app-liveness] ${r.slug}: its app answers at ${h.serviceUrl} — live`); }
   }
-  return { checked: rows.length, live };
+  // The project's SANDBOX (ADR 0406, task 1005289) gets the same knock until its first
+  // answer, then never again: it sleeps on the free plan, and a knock would wake it.
+  const { rows: sbs } = await db.query(
+    `SELECT id, slug, app_host->'sandbox' AS sb FROM provisioning_instances
+      WHERE app_host->>'platform' = 'render' AND app_host->'sandbox'->>'state' = 'deploying'
+        AND status <> 'torn_down'
+      ORDER BY id LIMIT ${SWEEP_LIMIT}`);
+  // the same few-at-a-time knocking as the apps above, so one slow sandbox holds none up
+  const sbAnswers = [];
+  for (let i = 0; i < sbs.length; i += CONCURRENCY) {
+    const batch = sbs.slice(i, i + CONCURRENCY);
+    sbAnswers.push(...(await Promise.all(batch.map((r) => appAnswers((r.sb || {}).serviceUrl, { fetchImpl: deps.fetchImpl, timeoutMs: deps.timeoutMs })))));
+  }
+  for (const [i, r] of sbs.entries()) {
+    const sb = r.sb || {};
+    if (!sbAnswers[i]) continue;
+    const { rowCount } = await db.query(
+      `UPDATE provisioning_instances
+          SET app_host = jsonb_set(app_host, '{sandbox}', (app_host->'sandbox') || jsonb_build_object('state', 'live', 'liveAt', now()::text))
+        WHERE id = $1 AND app_host->'sandbox'->>'state' = 'deploying'`, [r.id]);
+    if (rowCount) { live++; log(`[app-liveness] ${r.slug}: its sandbox answers at ${sb.serviceUrl} — live`); }
+  }
+  return { checked: rows.length + sbs.length, live };
 }
 
 function start(deps = {}) {

package/modules/provisioning/render-sandbox.js

@@ -0,0 +1,113 @@
+// modules/provisioning/render-sandbox.js — the web tier's half of a project's SANDBOX on
+// Render (task 1005289; ADR 0406, ADR 0327).
+//
+// WHY. Every project whose app runs on Render gets a second, free app from the same
+// repository that follows `main`, so finished work reaches a test copy first (ADR 0406 §2).
+// A new connection asks for one by itself (render-standup.js appHostFrom sets
+// `sandboxWanted`); an existing project adds one here with one action; the owner reads its
+// address and state beside the app's, in the same shape (app-status.js); and a teardown
+// removes it when the owner lends their key with it.
+//
+// Like the rest of this module the web tier never calls Render (ADR 0111 §2): it queues a
+// `render-standup` intent carrying the encrypted key, and the runner
+// (scripts/bongos/provision-render-sandbox.js) does the work and clears the key.
+'use strict';
+
+const { appStatus } = require('./app-status');
+
+// The sandbox's own database starts EMPTY: the platform cannot know an app's tables, so
+// the fake data is the app's own seed, run when it sees BONGOS_SANDBOX=1 (the starter's
+// half, task 1005291). Said to the owner plainly rather than promised.
+const READY_DB_NOTE = 'It has its own database, separate from your live data. It starts empty: your app fills it with test data when it runs as a sandbox.';
+
+// Why a project cannot have a sandbox right now, in the owner's words, or null.
+function noSandboxReason(inst) {
+  const h = (inst && inst.app_host) || {};
+  if (!inst || inst.status === 'torn_down' || inst.status === 'tearing_down') return 'This project has been removed, so it has no sandbox.';
+  if (!h.platform) return 'Your project has no app yet, so there is nothing to run in a sandbox. One is set up as soon as you connect your app to Render.';
+  if (h.platform !== 'render') return 'Sandboxes are set up on Render only, and your app runs somewhere else.';
+  if (!h.serviceId || !['deploying', 'linked', 'live'].includes(h.state)) return 'Your app is not set up on Render yet. Its sandbox is set up with it.';
+  return null;
+}
+
+// The owner's view of the sandbox: app-status.js's shape (stage, address, links, a
+// failure as one sentence) plus what its database is and whether one can be added.
+// Read from the row alone.
+function sandboxStatus(inst, { now = Date.now() } = {}) {
+  const h = (inst && inst.app_host) || {};
+  const sb = h.sandbox;
+  const live = !sb || sb.state === 'removed';
+  if (live && !h.sandboxWanted) {
+    const why = noSandboxReason(inst);
+    return { state: 'none', message: why || 'This project has no sandbox yet.', can_add: !why };
+  }
+  if (!sb || sb.state === 'requested') {
+    const why = h.platform === 'render' && h.state === 'failed' ? 'Your app’s setup on Render stopped, so its sandbox is waiting for it.' : null;
+    return { state: 'requested', stage: 'creating', message: why || 'Your sandbox is set up right after your app.', can_add: false };
+  }
+  if (sb.state === 'left') return { state: 'left', error: sb.error || 'The sandbox is still on your Render account.', can_add: false };
+  const s = appStatus({ platform: 'render', state: sb.state, serviceId: sb.serviceId, serviceUrl: sb.serviceUrl, updatedAt: sb.updatedAt, error: sb.error }, { now });
+  return {
+    ...s,
+    retry: undefined,
+    plan: 'free',
+    follows: 'main',
+    database: { state: sb.database || 'none', note: sb.dbNote || (sb.database === 'ready' ? READY_DB_NOTE : null) },
+    can_add: sb.state === 'failed' && !noSandboxReason(inst),
+  };
+}
+
+// Queue an existing project's sandbox: a render-standup intent holding the key, and the
+// row marked to want one, in ONE statement — the enqueueRenderStandup pattern, so an
+// open-intent collision keeps nothing. Returns { intent } or { conflict, intent }.
+async function enqueueSandboxAdd(db, instanceId, { keyEnc, requestedBy }) {
+  await require('./control-plane-guard').assertIntentAllowed(db, instanceId, 'render-standup');
+  try {
+    const { rows } = await db.query(
+      `WITH i AS (
+         INSERT INTO provisioning_intents (instance_id, action, requested_by, state, borrowed_key_enc)
+         VALUES ($1, 'render-standup', $2, 'pending', $3) RETURNING *
+       ), u AS (
+         UPDATE provisioning_instances
+            SET app_host = app_host || jsonb_build_object('sandboxWanted', true,
+                  'sandbox', COALESCE(app_host->'sandbox', '{}'::jsonb) || jsonb_build_object('state', 'requested', 'error', NULL))
+          WHERE id = $1 RETURNING id
+       )
+       SELECT i.id, i.instance_id, i.action, i.state, i.created_at FROM i`,
+      [instanceId, requestedBy ?? null, keyEnc]);
+    return { intent: rows[0] };
+  } catch (e) {
+    if (e && e.code === '23505') {
+      const { rows } = await db.query(
+        `SELECT id, action, state FROM provisioning_intents
+          WHERE instance_id = $1 AND state IN ('pending', 'running') ORDER BY created_at DESC LIMIT 1`, [instanceId]);
+      return { conflict: 'open_intent', intent: rows[0] || { action: 'unknown', state: 'open' } };
+    }
+    throw e;
+  }
+}
+
+// Put the owner's key on a teardown that is still pending, so the runner can remove the
+// sandbox (and only the sandbox). The table's CHECK refuses a key on a resolved intent.
+async function lendKeyToTeardown(db, intentId, keyEnc) {
+  const { rowCount } = await db.query(
+    `UPDATE provisioning_intents SET borrowed_key_enc = $2, updated_at = now()
+      WHERE id = $1 AND action = 'teardown' AND state = 'pending'`, [intentId, keyEnc]);
+  return rowCount > 0;
+}
+
+// The teardown route's half: the owner's Render key, sent as the `x-render-key` header
+// (a header, not a body: the kernel's audit log keeps a copy of write bodies), lent to the
+// teardown just queued so the runner can remove the sandbox. Returns whether it was lent.
+// A missing or malformed key, a teardown that was not just created, or a platform that
+// cannot seal a key safely each lend nothing, and the teardown goes ahead without it.
+const KEY_RE = /^rnd_[A-Za-z0-9]{16,128}$/;
+async function lendKeyFromRequest(db, req, teardown, secretBox) {
+  if (!teardown || !teardown.created || !teardown.intent) return false;
+  const key = String((req.headers && req.headers['x-render-key']) || '').trim();
+  if (!KEY_RE.test(key)) return false;
+  if (!secretBox || !secretBox.isConfigured()) return false;
+  return module.exports.lendKeyToTeardown(db, teardown.intent.id, secretBox.encrypt(key)); // through the export, so a test can stand in for the write
+}
+
+module.exports = { noSandboxReason, sandboxStatus, enqueueSandboxAdd, lendKeyToTeardown, lendKeyFromRequest };

package/modules/provisioning/render-standup.js

@@ -84,7 +84,9 @@ function badRequest(body) {
 
 // What the row records about the request — ids and plans, never the key.
 function appHostFrom(body) {
-  const h = { platform: 'render', mode: body.mode, ownerId: body.owner_id, state: 'requested', error: null };
+  // Every app on Render gets a sandbox beside it (ADR 0406, task 1005289): the runner sets
+  // it up after the app, with the same key (scripts/bongos/provision-render-sandbox.js).
+  const h = { platform: 'render', mode: body.mode, ownerId: body.owner_id, state: 'requested', error: null, sandboxWanted: true };
   if (body.mode === 'adopt') h.serviceId = body.service_id;
   if (body.mode === 'greenfield') {
     h.runtime = body.runtime;

package/modules/provisioning/routes/provisioning.js

@@ -50,6 +50,7 @@
 const crypto = require('node:crypto');
 const express = require('express');
 const api = require('../../../src/module-api');
+const renderSandbox = require('../render-sandbox');
 const auth = api, { pool, validateOrRespond, parseId } = api;
 const provisioning = require('../provisioning');
 const { costLedger, ownerMonthlyUsd } = require('../cost-ledger');
@@ -1002,6 +1003,8 @@ module.exports = function provisioningRoutes() {
           message: `A '${r.intent.action}' run is currently ${r.intent.state} for this instance — the teardown could not be queued; retry in a moment.`,
           details: { action: r.intent.action, state: r.intent.state } });
       }
+      // An optional Render key (x-render-key) lets the runner remove the project's sandbox — never the live app (ADR 0406 §7, task 1005289).
+      const lent = await renderSandbox.lendKeyFromRequest(pool, req, r, api.secretBox);
       if (r.created) {
         const who = isProjectOwner(inst, req.builder) ? 'owner' : `archon ${req.builder.github_login || req.builder.id}`;
         await provisioning.recordEvent(pool, {
@@ -1010,7 +1013,7 @@ module.exports = function provisioningRoutes() {
           actor,
         }).catch(() => {});
       }
-      res.json({ ok: true, queued: r.created, action: 'teardown', status: inst.status, superseded: r.superseded,
+      res.json({ ok: true, queued: r.created, action: 'teardown', status: inst.status, superseded: r.superseded, sandbox_key_lent: lent,
         message: r.created ? 'Your instance will be torn down shortly.' : 'A teardown is already queued for that instance.' });
     } catch (err) {
       log.error('[provisioning] POST /provisioning/instances/:id/teardown', err);

package/modules/provisioning/routes/render-standup.js

@@ -25,6 +25,7 @@ const renderStandup = require('../render-standup');
 const { failFrom } = require('../public-refusal');
 const { lookupRender, RenderLookupError } = require('../render-lookup');
 const { appStatus } = require('../app-status');
+const renderSandbox = require('../render-sandbox');
 const envManifest = require('../env-manifest');
 const { makeAskRateLimiter } = require('../rate-limit');
 
@@ -51,6 +52,8 @@ module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
   const router = express.Router();
   const lookupLimit = makeAskRateLimiter({ windowMs: 60_000, max: 20, key: (req) => `b:${req.builder && req.builder.id}` });
   const statusLimit = makeAskRateLimiter({ windowMs: 60_000, max: 60, key: (req) => `s:${req.builder && req.builder.id}` });
+  // Adding a sandbox queues work on the owner's account, so a handful a minute is plenty.
+  const sandboxLimit = makeAskRateLimiter({ windowMs: 60_000, max: 10, key: (req) => `x:${req.builder && req.builder.id}` });
 
   // POST /provisioning/render/lookup — rank: any authenticated builder. What the owner's
   // Render key can see: its workspaces, and the web services in the one they name. The
@@ -100,13 +103,58 @@ module.exports = function buildRenderStandupRouter({ fetchImpl } = {}) {
       const envVars = app && app.state !== 'disconnected'
         ? (await envManifest.listEnvVars(pool, id)).map((v) => ({ name: v.name, required: v.required !== false, set_for_you: dbSet && v.name === 'DATABASE_URL' }))
         : [];
-      res.json({ ok: true, app, env_vars: envVars, values_held: false });
+      // The sandbox beside it (ADR 0406, task 1005289), in the same shape.
+      const sandbox = renderSandbox.sandboxStatus(inst);
+      res.json({ ok: true, app, sandbox, env_vars: envVars, values_held: false });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/instances/:id/render', err && err.message);
       failFrom(res, err, 'render_status_failed');
     }
   });
 
+  // POST /provisioning/instances/:id/render/sandbox — rank: any authenticated builder, and
+  // OWNER ONLY, like every Render route. An app already on Render adds its sandbox with
+  // one action (ADR 0406, task 1005289): the owner lends the key once, and the runner sets
+  // up a free app that follows main, beside the live one, which it does not touch. A
+  // project with no app on Render is told why it has none. The reply is a receipt.
+  router.post('/provisioning/instances/:id/render/sandbox', api.requireBuilder, sandboxLimit, async (req, res) => {
+    const id = parseId(req, res, { positiveInt: true });
+    if (!id) return;
+    if (validateOrRespond(req, res, { key: { required: true, type: 'string', maxLength: 200 } })) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!ownedBy(inst, req.builder)) return res.fail('instance_not_found', 404);
+      if (!renderStandup.KEY_RE.test(req.body.key)) {
+        return res.fail('render_request_invalid', { status: 400, message: 'That doesn’t look like a Render API key. It starts with “rnd_”.' });
+      }
+      const why = renderSandbox.noSandboxReason(inst);
+      if (why) return res.fail('sandbox_unavailable', { status: 409, message: why });
+      const sb = inst.app_host && inst.app_host.sandbox;
+      if (sb && ['creating', 'deploying', 'live'].includes(sb.state)) {
+        return res.fail('sandbox_exists', { status: 409, message: 'This project already has a sandbox.' });
+      }
+      if (!api.secretBox.isConfigured()) {
+        return res.fail('render_unavailable', { status: 503, message: 'The platform can’t take a key safely right now, so nothing was sent. Try again later.' });
+      }
+      const r = await renderSandbox.enqueueSandboxAdd(pool, id, { keyEnc: api.secretBox.encrypt(req.body.key), requestedBy: 'api:self' });
+      if (r.conflict) {
+        return res.fail('intent_conflict', { status: 409,
+          message: `A '${r.intent.action}' run is ${r.intent.state} for this project, so your key was not kept. Try again once it has finished.`,
+          details: { action: r.intent.action, state: r.intent.state } });
+      }
+      await provisioning.recordEvent(pool, {
+        instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'render-standup',
+        detail: 'Render sandbox requested by owner', actor: 'api:self',
+      }).catch(() => {});
+      res.json({ ok: true, queued: true, action: 'render-standup', sandbox: true,
+        message: 'Queued. The platform will add a free sandbox app on your Render account that updates with every finished change. Your live app is not touched. Your key is used once and then thrown away.' });
+    } catch (err) {
+      // Never log the request: it carries the key.
+      log.error('[provisioning] POST /provisioning/instances/:id/render/sandbox', err && err.message);
+      failFrom(res, err, 'render_sandbox_failed');
+    }
+  });
+
   // POST /provisioning/instances/:id/render — rank: any authenticated builder, and OWNER
   // ONLY: the key is the owner's and so is the account it acts in, so an archon on
   // someone else's project gets the same 404 as a stranger. The reply is a receipt;

package/modules/provisioning/seams.js

@@ -7,6 +7,8 @@ const api = require('../../src/module-api');
 const { pool } = api;
 const provisioning = require('./provisioning');
 const { selfUpdateChannel } = require('./core-upgrade');
+const { appStatus } = require('./app-status');
+const { sandboxStatus } = require('./render-sandbox');
 const { ALWAYS_ON_CORE, optionalModules } = require('./starter-bundles');
 
 // The `provisioning.projectPublishIdentity` port (task 1003578, ADR 0247 D4): the name and
@@ -29,6 +31,32 @@ async function projectPublishIdentity(db, { slug, host } = {}) {
   return rows[0] ? { name: rows[0].slug, description: rows[0].description } : null;
 }
 
+// The `provisioning.projectAppStatus` port (task 1004571): where a hosted project's APP runs,
+// for that project's own hall. The hall asks the hub over the client-authenticated SSO route
+// (platform-identity routes/sso-app-status.js), which names the project by BOTH halves of the
+// ADR 0246 projection, as projectPublishIdentity does. The answer is app-status.js's own
+// shape — never a second one — read from the row alone (nothing here calls Render), with the
+// same "a lent key not yet spent means wait" reading the owner's route makes.
+// The sandbox beside a Render app (ADR 0406, task 1005289) rides along in render-sandbox.js's
+// own shape, the one the owner's route returns; null when the app is not on Render.
+// null = no such project on this plane; { app: null } = a project whose app has no platform.
+async function projectAppStatus(db, { slug, host } = {}) {
+  if (typeof slug !== 'string' || !slug || typeof host !== 'string' || !host) return null;
+  const { rows } = await db.query(
+    `SELECT i.app_host, i.status,
+            EXISTS (SELECT 1 FROM provisioning_intents p
+                     WHERE p.instance_id = i.id AND p.state IN ('pending', 'running')
+                       AND p.borrowed_key_enc IS NOT NULL) AS waiting
+       FROM provisioning_instances i
+      WHERE i.slug = $1 AND lower(i.domain) = $2
+      LIMIT 1`,
+    [slug, host.toLowerCase()],
+  );
+  if (!rows[0]) return null;
+  const app = appStatus(rows[0].app_host, { keyWaiting: rows[0].waiting === true });
+  return { app, sandbox: app && app.platform === 'render' ? sandboxStatus(rows[0]) : null };
+}
+
 // Idempotent — the loader calls the routes factory once at boot, but tests may
 // instantiate the router repeatedly; gating on hasProvider keeps each port
 // single-registered.
@@ -45,6 +73,8 @@ async function projectPublishIdentity(db, { slug, host } = {}) {
 //     question names both halves of the ADR 0246 projection.
 //   • PROVIDES port `provisioning.projectPublishIdentity` ({ slug, host }) → { name,
 //     description } | null — see projectPublishIdentity above.
+//   • PROVIDES port `provisioning.projectAppStatus` ({ slug, host }) → { app, sandbox } | null — see
+//     projectAppStatus above.
 //   • PROVIDES port `provisioning.moduleCatalog` () → { core: [key], optional: [{ key,
 //     label, summary }] } — the modules a NEW project gets and may opt into, with the
 //     owner-facing words the creation picker shows (task 1005273). The start-a-project
@@ -57,10 +87,11 @@ function registerProvisioningSeams() {
   api.registerProvider('provisioning.projectOwnedBy', (target) => provisioning.projectOwnedBy(pool, target));
   api.registerProvider('provisioning.projectPublishIdentity', (target) => projectPublishIdentity(pool, target));
   api.registerProvider('provisioning.selfUpdateChannel', () => selfUpdateChannel(pool));
+  api.registerProvider('provisioning.projectAppStatus', (target) => projectAppStatus(pool, target));
   api.registerProvider('provisioning.moduleCatalog', () => ({
     core: [...ALWAYS_ON_CORE],
     optional: optionalModules().map(({ key, label, summary }) => ({ key, label, summary })),
   }));
 }
 
-module.exports = { registerProvisioningSeams, projectPublishIdentity };
+module.exports = { registerProvisioningSeams, projectPublishIdentity, projectAppStatus };

package/modules/provisioning/starter-bundles.js

@@ -45,6 +45,7 @@
 // layers on, not part of any bundle, and they are listed here so a creation form
 // can show an owner what they already have without a second round trip.
 const ALWAYS_ON_CORE = Object.freeze([
+  'app-host',
   'autonomy',
   'builder-settings',
   'copy-desk',