@bongos/core 1.25.15 → 1.25.17

package/modules/lifecycle/kickoff-seed.js

@@ -85,6 +85,7 @@ async function seedGenesisStages({ builderId = null, existing = false } = {}, de
   const pool = deps.pool || api.pool;
   const insert = deps.createTask || ((row) => db.createTask(row));
   const find = deps.findTaskBySourceRef || ((q) => db.findTaskBySourceRef(q));
+  const addDep = deps.addTaskDependency || ((id, dep) => db.addTaskDependency(id, dep));
   const { rows: versions } = await pool.query(FIRST_VERSION_SQL);
   if (!versions.length) return { seeded: 0, skipped: 'no_version' };
   const versionId = versions[0].id;
@@ -109,18 +110,39 @@ async function seedGenesisStages({ builderId = null, existing = false } = {}, de
       seeded += 1;
     }
   }
+  // task 1005110: the order genesisChecklist declares becomes a real edge, so the claim
+  // gate refuses the later step (DEPS_NOT_SHIPPED) until the earlier one ships. Written
+  // for steps already filed too (ON CONFLICT DO NOTHING), so a re-run repairs a missing edge.
+  for (const steps of Object.values(genesisChecklist({ existing }))) {
+    for (const t of steps) {
+      if (!t.after) continue;
+      const [me, before] = await Promise.all([
+        find({ source: GENESIS_SOURCE, sourceRef: t.ref }),
+        find({ source: GENESIS_SOURCE, sourceRef: t.after }),
+      ]);
+      if (me && before) await addDep(me.id, before.id);
+    }
+  }
   return { seeded, versionId };
 }
 
-// genesisStageTasks(deps) → { stageKey: [{ id, title, status, description }] } for every
-// genesis task on the board, grouped by the stage its source_ref names. The genesis home
-// lists them, and a stage close hands their ids to the Board Room's finished-tasks gate.
+// genesisStageTasks(deps) → { stageKey: [{ id, title, status, description, waits_on }] } for
+// every genesis task on the board, grouped by the stage its source_ref names. The genesis
+// home lists them, and a stage close hands their ids to the Board Room's finished-tasks gate.
+// `waits_on` is [{ id, title }] of the tasks it depends on that have not shipped: the claim
+// gate's own rule (unsatisfiedDeps, abandoned still blocks), so a row drawn locked is one
+// POST /claims would refuse (task 1005110).
 // The description rides along so each row's Copy prompt carries the task's own words
 // (task 1005109); the read stays bounded, it is only the few seeded genesis tasks.
 async function genesisStageTasks(deps = {}) {
   const pool = deps.pool || api.pool;
   const { rows } = await pool.query(
-    `SELECT id, title, status, description, source_ref FROM tasks WHERE source = $1 ORDER BY id ASC`,
+    `SELECT t.id, t.title, t.status, t.description, t.source_ref,
+            COALESCE((SELECT json_agg(json_build_object('id', x.id, 'title', x.title) ORDER BY x.id)
+                        FROM dependencies d JOIN tasks x ON x.id = d.to_id
+                       WHERE d.from_kind = 'task' AND d.from_id = t.id
+                         AND d.to_kind = 'task' AND x.status <> 'shipped'), '[]'::json) AS waits_on
+       FROM tasks t WHERE t.source = $1 ORDER BY t.id ASC`,
     [GENESIS_SOURCE],
   );
   const out = {};
@@ -129,6 +151,7 @@ async function genesisStageTasks(deps = {}) {
     if (!stage) continue;
     (out[stage] = out[stage] || []).push({
       id: String(r.id), title: r.title, status: r.status, description: r.description || '',
+      waits_on: (Array.isArray(r.waits_on) ? r.waits_on : []).map((w) => ({ id: String(w.id), title: w.title })),
     });
   }
   return out;

package/modules/lifecycle/migrations/lifecycle_022_repo_maps.sql

@@ -0,0 +1,44 @@
+-- lifecycle_022_repo_maps.sql — the first read-through's repository maps (task 1005280,
+-- goal 1000106).
+--
+-- WHAT IT IS. A project that arrives with code gets a prompt for the owner's OWN AI
+-- session; that session reads the repository on the owner's computer and subscription
+-- and sends back a map (modules/lifecycle/first-read.js). A map waits here as `pending`
+-- until the owner accepts it — whole or item by item — or rejects it. Nothing is filed
+-- by the submit itself.
+--
+-- WHY A SECOND TABLE. Re-running the read-through must not file the same goal or task
+-- twice, and goals carry no source_ref to dedup on. So every accepted item's stable
+-- `ref` (derived from its title, never its position) is a row in
+-- lifecycle_repo_map_filed, PRIMARY KEY on the ref: the next accept skips it, whichever
+-- map names it again.
+--
+-- MODULE-OWNED and `lifecycle_`-prefixed (ADR 0083 §Decision #5).
+
+CREATE TABLE IF NOT EXISTS lifecycle_repo_maps (
+  id            bigserial PRIMARY KEY,
+  schema        text NOT NULL,
+  map           jsonb NOT NULL,
+  status        text NOT NULL DEFAULT 'pending',
+  submitted_by  bigint REFERENCES builders(id),
+  submitted_at  timestamptz NOT NULL DEFAULT now(),
+  reviewed_by   bigint REFERENCES builders(id),
+  reviewed_at   timestamptz,
+
+  CONSTRAINT lifecycle_repo_maps_status_chk
+    CHECK (status IN ('pending', 'accepted', 'rejected'))
+);
+
+CREATE INDEX IF NOT EXISTS lifecycle_repo_maps_newest_idx
+  ON lifecycle_repo_maps (submitted_at DESC);
+
+CREATE TABLE IF NOT EXISTS lifecycle_repo_map_filed (
+  ref        text PRIMARY KEY,
+  kind       text NOT NULL,
+  entity_id  bigint NOT NULL,
+  map_id     bigint NOT NULL REFERENCES lifecycle_repo_maps(id),
+  filed_by   bigint REFERENCES builders(id),
+  filed_at   timestamptz NOT NULL DEFAULT now(),
+
+  CONSTRAINT lifecycle_repo_map_filed_kind_chk CHECK (kind IN ('goal', 'task'))
+);

package/modules/lifecycle/module.json

@@ -38,7 +38,8 @@
       "home-city",
       "home-gallery",
       "task-votes",
-      "notes"
+      "notes",
+      "first-read"
     ],
     "pollers": [
       "publish-reconciler"

package/modules/lifecycle/routes/first-read.js

@@ -0,0 +1,79 @@
+// modules/lifecycle/routes/first-read.js — the HTTP surface of the first read-through
+// (task 1005280, goal 1000106): hand out the prompt, take a repository map from the
+// owner's own AI session, show it for review, and accept or reject it.
+//
+// No route here calls an AI, reads a repository, or files anything on submit. Filing is
+// the accept route alone, gated like creating a goal (`goal.create` + the planning
+// act-alone rule), because accepting a map IS creating goals and tasks. The rules are
+// first-read.js; the store is first-read-db.js. Reaches core only through the doorway.
+
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const fr = require('../first-read');
+const store = require('../first-read-db');
+
+const { asyncHandler, parseId, validateOrRespond } = api;
+
+module.exports = function buildFirstReadRouter() {
+  const router = express.Router();
+
+  // rank: any-builder — the prompt and the shape are instructions, not project data.
+  router.get('/first-read/prompt', api.requireBuilder, (req, res) => {
+    res.json({ schema: fr.SCHEMA, file: fr.MAP_FILE, prompt: fr.firstReadPrompt(), example: fr.exampleMap(), limits: fr.LIMITS });
+  });
+
+  // rank: goal.create — a map is a planning proposal for this project. Stores it
+  // pending; files nothing. A malformed map is refused with every error named.
+  router.post('/first-read/maps', api.requireBuilder, api.requirePermission('goal.create'), asyncHandler('POST /first-read/maps', async (req, res) => {
+    // The envelope is checked here; the map inside it by first-read.js, which names every error.
+    if (validateOrRespond(req, res, { map: { required: true, type: 'object' } })) return undefined;
+    const out = await store.submitMap({ raw: req.body.map, builderId: req.builder.id });
+    if (!out.ok) return res.fail('invalid_map', 400, { errors: out.errors });
+    return res.status(201).json({
+      map_id: out.map_id, status: out.status,
+      items: out.items.map((i) => ({ ref: i.ref, type: i.type, title: i.title })),
+      next: 'Show the owner the map. File it only with their yes: POST /first-read/maps/' + out.map_id + '/accept { all: true } or { items: [ref] }.',
+    });
+  }, { errorCode: 'first_read_submit_failed' }));
+
+  // rank: goal.create — the review is for whoever may accept or reject it.
+  router.get('/first-read/maps/:id', api.requireBuilder, api.requirePermission('goal.create'), asyncHandler('GET /first-read/maps/:id', async (req, res) => {
+    const id = req.params.id === 'latest' ? 'latest' : parseId(req, res, { positiveInt: true });
+    if (id == null) return undefined;
+    const review = await store.reviewMap(id);
+    if (!review) return res.fail('not_found', 404);
+    return res.json(review);
+  }, { errorCode: 'first_read_review_failed' }));
+
+  // rank: goal.create + act-alone planning — the owner's yes. Files the chosen items as
+  // draft goals (open) and tasks (backlog); an item already filed is skipped.
+  router.post('/first-read/maps/:id/accept', api.requireBuilder, api.requirePermission('goal.create'), api.requireActAlone('planning'),
+    asyncHandler('POST /first-read/maps/:id/accept', async (req, res) => {
+      const mapId = parseId(req, res, { positiveInt: true });
+      if (mapId == null) return undefined;
+      if (validateOrRespond(req, res, {
+        all: { type: 'boolean' },
+        items: { type: 'array', itemsType: 'string', maxItems: 500 },
+      })) return undefined;
+      const { all, items } = req.body || {};
+      if ((all === true) === Array.isArray(items)) {
+        return res.fail('invalid_items', 400, { hint: 'send { all: true } or { items: [ref, …] } — the refs from the review' });
+      }
+      const out = await store.acceptMap({ mapId, select: all === true ? 'all' : items, builderId: req.builder.id });
+      if (!out.ok) { const { code, status, ...rest } = out; return res.fail(code, status, rest); }
+      return res.json(out);
+    }, { errorCode: 'first_read_accept_failed' }));
+
+  // rank: goal.create — the owner's no. Files nothing.
+  router.post('/first-read/maps/:id/reject', api.requireBuilder, api.requirePermission('goal.create'), asyncHandler('POST /first-read/maps/:id/reject', async (req, res) => {
+    const mapId = parseId(req, res, { positiveInt: true });
+    if (mapId == null) return undefined;
+    const out = await store.rejectMap({ mapId, builderId: req.builder.id });
+    if (!out.ok) { const { code, status, ...rest } = out; return res.fail(code, status, rest); }
+    return res.json(out);
+  }, { errorCode: 'first_read_reject_failed' }));
+
+  return router;
+};

package/modules/onboarding/genesis-home.js

@@ -143,10 +143,19 @@ function readPlanValue(raw) {
 
 const FINISHED = Object.freeze(['shipped', 'abandoned']); // the Board Room's own gate, mirrored for display
 
+// taskState(t) — one stage task as the checklist draws it (task 1005110).
+function taskState(t) {
+  const finished = FINISHED.includes(t.status);
+  const waits = finished ? [] : (Array.isArray(t.waits_on) ? t.waits_on : []);
+  return { ...t, finished, waits_on: waits, state: finished ? 'done' : waits.length ? 'locked' : 'open' };
+}
+
 // shapeGenesis({ mode, plan, tasks, board, stageAt }) — PURE. The genesis home's view.
 //   mode    foundingModeFor's shape (non-null)
 //   plan    the saved plan or null (deciding)
-//   tasks   { stage: [{ id, title, status, description }] }
+//   tasks   { stage: [{ id, title, status, description, waits_on }] }
+// Each task comes back with `state`: 'done' (finished), 'locked' (waits on an unshipped
+// task, named in `waits_on`) or 'open' — decided here, never re-derived in a browser.
 //   board   { stage: genesisStageStatus row } or {}
 //   stageAt { stage: ISO } — when each stage began, for its due date
 function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {} }) {
@@ -154,7 +163,7 @@ function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {} }) {
   const stages = PROPER.map((key) => {
     const info = STAGE_INFO[key];
     const idx = fm.STAGES.indexOf(key);
-    const list = (tasks[key] || []).map((t) => ({ ...t, finished: FINISHED.includes(t.status) }));
+    const list = (tasks[key] || []).map((t) => taskState(t));
     const b = board[key] || null;
     const allFinished = list.length > 0 && list.every((t) => t.finished);
     const onBoard = !!(b && (b.state === 'sitting' || b.state === 'passed'));

package/modules/onboarding/genesis-work.js

@@ -40,7 +40,7 @@
 // un-answer appends a history row, so the founder can see what an answer used to say.
 //
 // WHICH STAGES. A stage adopts the pattern by declaring its questions in QUESTIONS.
-// Strategize does here; scope's guided door is its project interview (task 1005114);
+// 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
 // no questions still takes a free page and a link.
 //
@@ -59,8 +59,30 @@ const LIMITS = Object.freeze({ answer: 4000, page: 20000, link: 500 });
 
 // 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.
+// of a good answer, shown under the question in every door. `group` (optional) is a
+// heading the guided door shows above the questions that share it.
+//
+// SCOPE IS THE PROJECT INTERVIEW (task 1005114): the questions every later goal and task
+// should be planned inside — what this is for, who it is for, and the bet — rather than
+// V1's edges, which is what came back thin before. The owner's starter set, as written;
+// the list is "not final" and the owner invited more. These are prose questions; the
+// closed-vocabulary ones (team shape, geography, entity, rewards) are the hub's project
+// detail and are not repeated here.
 const QUESTIONS = Object.freeze({
+  scope: Object.freeze([
+    Object.freeze({ id: 'what_creating', group: 'What and why', ask: 'In a few sentences, what are you creating with this project?',
+      hint: 'Say it the way you would to a friend. What exists when this is done that does not exist now?' }),
+    Object.freeze({ id: 'goal_impact', group: 'What and why', ask: 'What is your goal with it? What impact do you want it to have?',
+      hint: 'Why this is worth doing at all, and for whom it changes something.' }),
+    Object.freeze({ id: 'success_two_years', group: 'What and why', ask: 'In two years, what does success look like?',
+      hint: 'Something you could point at: who is using it, what they do with it, what it has become.' }),
+    Object.freeze({ id: 'reach_who', group: 'Who', ask: 'Who do you want to reach with this project?',
+      hint: 'The people it is ultimately for, not only the first ones. Be as specific as you can.' }),
+    Object.freeze({ id: 'work_with_who', group: 'Who', ask: 'Who do you want working on it with you?',
+      hint: 'The kind of people you hope join: their skills, how they work, what they care about.' }),
+    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.' }),
+  ]),
   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.' }),
@@ -118,7 +140,7 @@ function shapeStage(stage, work, answers = []) {
   const questions = questionsFor(stage).map((q) => {
     const a = byId.get(q.id);
     return {
-      id: q.id, ask: q.ask, hint: q.hint,
+      id: q.id, ask: q.ask, hint: q.hint, group: q.group || null,
       answer: a ? {
         state: a.state, text: a.answer_md || null, origin: a.origin,
         // A carried-over answer is shown as such until the founder makes it theirs.
@@ -196,11 +218,12 @@ function assistPrompt(stage) {
     '- Offer two or three options when I am stuck, never one confident answer.',
     '- "Not sure yet" is a fine answer. Record it as that rather than filling the gap for me.',
     '- Record an answer only after I say it is mine, in my words (you may tidy the wording; read it back first).',
+    '- Once I have answered, you may offer a draft page built only from my answers. I edit it; save it only when I say it is mine.',
     '',
   ];
   if (qs.length) {
-    lines.push('The questions:');
-    qs.forEach((q, i) => lines.push(`${i + 1}. ${q.ask} (${q.hint})`));
+    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})`));
     lines.push('');
   }
   lines.push('To see what I have already said:  npx bongos genesis show ' + stage);

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;