@bongos/core 1.20.83 → 1.21.1

package/docs/recipes/private-npm-distribution.md

@@ -57,7 +57,7 @@ npm publish ./clients/bongos-client               # real (publishConfig makes it
 
 **Publishing is automatic on merge** as of 2026-08-08: the `publish` workflow rides behind the required `unit` check and waits for the `integration` lane's verdict on the commit it releases (task 1004290), auto-bumps a patch when nobody bumped, builds through the fail-closed no-leak gate, publishes, and tags — see the workflow header (`.github/workflows/publish.yml`) and ADR 0161. It ships inert until the owner arms it: repo variable `PUBLISH_ON_MERGE=1`, a **trusted publisher** registered on npmjs.com for `@bongos/core` naming this repo + `publish.yml`, and the secret `RELEASE_PUSH_TOKEN` (contents:write, for the bump commit). There is deliberately **no** `NPM_TOKEN` — the lane authenticates by OIDC, and the workflow sets neither `NPM_TOKEN` nor `NODE_AUTH_TOKEN` because either one would send npm down the legacy token path and skip the OIDC exchange entirely. A **minor/major bump stays a human in-task edit**. The update subscription ([ADR 0136](../adr/0136-update-channel-subscription-policy.md)) consumes whatever is published, on its next sweep.
 
-**Candidates and Release** ([ADR 0361](../adr/0361-merges-publish-as-candidates-release-decides-what-others-are-offered.md), task 1004298). With the repo variable `PUBLISH_AS_CANDIDATE=1`, each merge publishes under the `next` label: the platform hall runs it, and no other project is offered it. **Release** on /deploy runs `publish.yml`'s `release` job (`workflow_dispatch`, input `release_version`), which moves `latest` to that version over the same OIDC trusted publisher. It needs **Allow npm dist-tag** ticked on the `publish.yml` trusted-publisher entry, and the server's GitHub App needs **Actions: write** to start the job. From a terminal the same job runs as `gh workflow run publish.yml -f release_version=<x.y.z>`. The arming order is in the ADR.
+**Candidates and Release** ([ADR 0361](../adr/0361-merges-publish-as-candidates-release-decides-what-others-are-offered.md), task 1004298). With the repo variable `PUBLISH_AS_CANDIDATE=1`, each merge publishes under the `next` label: the platform hall runs it, and no other project is offered it. **Release** on /deploy runs `publish.yml`'s `release` job (`workflow_dispatch`, input `release_version`), which moves `latest` to that version over the same OIDC trusted publisher. It needs **Allow npm dist-tag** ticked on the `publish.yml` trusted-publisher entry, and the server's GitHub credential needs **Actions: write** to start the job: the `GITHUB_PUSH_TOKEN` access token (what cloudbongos.com uses), or the GitHub App where one is configured. From a terminal the same job runs as `gh workflow run publish.yml -f release_version=<x.y.z>`. The arming order is in the ADR.
 
 The steps below remain as the **manual fallback** (lane disarmed, npm outage, or a deliberate out-of-band release):
 

package/migrations/core_269_session_transcripts.sql

@@ -0,0 +1,35 @@
+-- core_269_session_transcripts.sql — the FULL, secret-scrubbed transcript of every
+-- session (ADR 0051, task 1001004).
+--
+-- WHY A SEPARATE TABLE and not a widened session_records.detail / a new jsonb
+-- column on it: session_records is the BFG's hot, searched, paged table
+-- (searchSessions, summarizeSessions, /mine all SELECT from it, and its rows are
+-- KB by design — ADR 0027). A transcript is MB. Putting it on the same row would
+-- make every list query drag (or have to remember to exclude) a fat jsonb, and
+-- would make a TOASTed-column slip on one query a performance incident. One row
+-- per session in each table, joined on session_id, keeps the evaluator's read
+-- path exactly as cheap as it is today. ADR 0051 §1 allowed either shape
+-- ("new transcript jsonb column, or a widened detail"); this is the third
+-- option that satisfies its intent without the cost.
+--
+-- The content is scrubbed ON THE BUILDER'S BOX before upload (modules/security/
+-- secret-scrub.js, the task-1003 scrubber); this table never holds raw text.
+--
+-- builder_id is denormalised from session_records ON PURPOSE: the read route's
+-- ownership check (own transcript vs Archon-only cross-builder) must not depend
+-- on a join succeeding, and the upload's ownership guard needs it at write time.
+--
+-- Retention: keep forever (ADR 0051 §4, Lars 2026-06-13). Storage-cost work is a
+-- deliberate future task, not designed in here.
+
+CREATE TABLE IF NOT EXISTS session_transcripts (
+  session_id    text PRIMARY KEY,                       -- Claude Code session id, == session_records.session_id
+  builder_id    bigint NOT NULL REFERENCES builders(id),
+  turn_count    integer NOT NULL DEFAULT 0,
+  byte_size     integer NOT NULL DEFAULT 0,             -- serialized size of `turns`, for corpus accounting
+  truncated     boolean NOT NULL DEFAULT false,         -- true when the uploader hit its own size ceiling
+  turns         jsonb NOT NULL DEFAULT '[]'::jsonb,     -- per-turn scrubbed content (prompts, assistant text, tool calls + results)
+  uploaded_at   timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_transcripts_builder ON session_transcripts (builder_id);

package/modules/hall-ui/public/genesis-home.js

@@ -79,7 +79,7 @@
     var now = g.stages.find(function (s) { return s.state === 'now'; });
     var sub = g.deciding
       ? 'Deciding the plan' + (g.day ? ' · day ' + g.day : '')
-      : 'Stage ' + g.stage_number + ' of ' + g.stage_count + ' · ' + (now ? now.label.toLowerCase() : g.stage) + (g.day ? ' · day ' + g.day : '');
+      : 'Stage ' + g.stage_number + ' of ' + g.stage_count + ' · ' + (now ? now.label.toLowerCase() : g.stage) + (g.demo ? ' · demo' : g.day ? ' · day ' + g.day : '');
     return '<div class="genesis__head"><h2 id="genesis-h" class="scroll__h">Genesis</h2>'
       + '<p class="genesis__sub">' + esc(sub) + '</p></div>' + stepperHtml(g);
   }
@@ -157,7 +157,10 @@
   function stagesHtml(g) {
     return '<ol class="genesis__stages">' + g.stages.map(function (s) {
       var wakes = (s.wakes || []).map(function (id) { return ROOM[id] || id; });
-      var due = s.state === 'now' && s.due ? ' · due ' + new Date(s.due).toLocaleDateString(undefined, { month: 'short', day: 'numeric' }) : '';
+      // A demo's stage is minutes long (task 1004506): say how long, and due at a time.
+      var due = s.minutes
+        ? ' · ' + s.minutes + ' min' + (s.state === 'now' && s.due ? ', due ' + new Date(s.due).toLocaleTimeString(undefined, { hour: 'numeric', minute: '2-digit' }) : '')
+        : s.state === 'now' && s.due ? ' · due ' + new Date(s.due).toLocaleDateString(undefined, { month: 'short', day: 'numeric' }) : '';
       return '<li class="genesis__stage is-' + s.state + '">'
         + '<span class="genesis__stage-n">0' + s.number + '</span>'
         + '<span class="genesis__stage-t"><b>' + esc(s.label) + '</b>'
@@ -225,12 +228,23 @@
     return document.documentElement.getAttribute('data-founding') === 'on';
   }
 
+  // A demo's genesis is expedited (task 1004506): its plan was settled from the demo's
+  // own picks before anyone saw it, so it never shows the decide form, only this line.
+  function demoHtml(g) {
+    var d = g.demo;
+    if (!d) return '';
+    var total = g.stages.reduce(function (n, s) { return n + (s.minutes || 0); }, 0);
+    return '<p class="scroll__lede">A demo’s genesis is short: about ' + esc(String(total)) + ' minutes, then the rest of your time is for building. '
+      + 'The plan is already set from your demo: Monarchy / BDFL, ' + esc(String(d.people)) + (d.people === 1 ? ' person, ' : ' people, ')
+      + esc(String(d.hours_each)) + (d.hours_each === 1 ? ' hour' : ' hours') + ' each. Finish each stage’s task, then approve it to move on.</p>';
+  }
+
   function render(host, state) {
     var g = state.genesis;
     if (!g) { host.hidden = true; return; }
     host.innerHTML = headHtml(g) + (g.deciding
       ? decideHtml(g, state.gov)
-      : lifeHtml(g) + '<div class="genesis__grid">' + stagesHtml(g) + nowHtml(g, state.viewer) + '</div>');
+      : demoHtml(g) + lifeHtml(g) + '<div class="genesis__grid">' + stagesHtml(g) + nowHtml(g, state.viewer) + '</div>');
     host.hidden = false;
   }
 

package/modules/hall-ui/public/index-genesis-demo.states.json

@@ -0,0 +1,13 @@
+{
+  "_": "The genesis home of a DEMO, born into genesis (task 1004506): 3 people, 4 hours each. The plan was settled at birth from the demo's picks, so there is no decide form: one line names the plan, and each stage reads in minutes (scope in progress, due at a time). /me says founding at scope (kit fixture me-founding-demo.json) and /founding/genesis answers founding-genesis-demo.json, built from the real server shaper. A real project's genesis is index-genesis.states.json and index-genesis-decide.states.json; a hall that is not founding is index.states.json.",
+  "page": "/builders/",
+  "surface": "hall-ui",
+  "stub": { "prefix": "/builders/", "fixtures": { "me": "me-founding-demo", "founding-genesis": "founding-genesis-demo" } },
+  "modeQuery": false,
+  "ignoreRequests": ["/api/(gds|bongos)/me$", "/api/(gds|bongos)/me/", "/api/(gds|bongos)/tasks", "/api/(gds|bongos)/claims", "/api/(gds|bongos)/goals", "/api/(gds|bongos)/inbox", "/api/(gds|bongos)/live", "/api/(gds|bongos)/analytics/", "/api/(gds|bongos)/achievements", "/api/(gds|bongos)/versions", "/api/(gds|bongos)/leaderboard", "/api/(gds|bongos)/removal-proposals", "/api/(gds|bongos)/blockers"],
+  "_ignored": "removal-proposals and blockers are fixtures the kit stub does not carry; index.states.json's home render reports the same two 404s.",
+  "ignoreConsole": ["/api/(gds|bongos)/", "\\b401\\b", "\\b404\\b", "Unauthorized", "Not Found", "load failed"],
+  "states": {
+    "demo": { "auth": true, "actions": [["wait", 800]], "expect": { "visible": ["#genesis-home", "#founding-band"] } }
+  }
+}

package/modules/lifecycle/workflow-dispatch.js

@@ -5,16 +5,21 @@
 // Kept beside github-push.js rather than in it: it shares that file's credential and headers,
 // and nothing else.
 
-const { resolveToken, ghHeaders, isSafeBranch } = require('./github-push');
+const { getInstallationToken, ghHeaders, isSafeBranch } = require('./github-push');
 const { repoInfo: { loadRepoInfo } } = require('../../src/module-api');
 
 // dispatchWorkflow — start a GitHub Actions workflow on this repo (task 1004298, ADR 0361). The
 // Release button on /deploy uses it to run publish.yml's release job, so the npm credential never
-// leaves GitHub: the server holds only the GitHub App key it already holds, and the App needs
-// Actions: write for this one call. Returns { ok:true } on GitHub's 204, otherwise
-// { ok:false, code, status? } — UNCONFIGURED (no credential), NO_REPO_INFO, BAD_INPUT, REFUSED
-// (GitHub said no: 403 = the App lacks Actions: write, 404 = no such workflow or no access,
-// 422 = an input the workflow does not declare), UNREACHABLE. Never throws.
+// leaves GitHub: the server uses only the GitHub credential it already holds, which needs
+// Actions: write for this one call. Returns { ok:true, credential } on GitHub's 204, otherwise
+// { ok:false, code, status?, credential? } — UNCONFIGURED (no credential), NO_REPO_INFO, BAD_INPUT,
+// REFUSED (GitHub said no: 403 = the credential lacks Actions: write, 404 = no such workflow or no
+// access, 422 = an input the workflow does not declare), UNREACHABLE. Never throws.
+//
+// `credential` says WHICH one was used — 'app' (a GitHub App installation token) or 'token' (the
+// GITHUB_PUSH_TOKEN access token) — so a refusal can name the thing the owner must edit
+// (task 1004518: cloudbongos.com uses the access token, and a message naming "the App" sent the
+// owner to the wrong settings page). Resolved in resolveToken's order: App first, then the token.
 //
 // ONLY THE WORKFLOWS NAMED HERE can be started. The port lends the server's GitHub credential to
 // another module; an allowlist keeps a buggy or future borrower from running any other workflow in
@@ -22,8 +27,13 @@ const { repoInfo: { loadRepoInfo } } = require('../../src/module-api');
 const DISPATCHABLE_WORKFLOWS = Object.freeze(['publish.yml']);
 async function dispatchWorkflow({ workflow, ref = 'main', inputs = {} }, deps = {}) {
   if (!DISPATCHABLE_WORKFLOWS.includes(String(workflow || '')) || !isSafeBranch(ref)) return { ok: false, code: 'BAD_INPUT' };
-  let token;
-  try { token = await resolveToken(deps); } catch (_) { return { ok: false, code: 'UNCONFIGURED' }; }
+  let token = deps.token || null;
+  let credential = token ? (deps.credential || 'token') : null;
+  if (!token) {
+    try { token = await (deps.appToken || getInstallationToken)(deps); } catch (_) { return { ok: false, code: 'UNCONFIGURED', credential: 'app' }; }
+    if (token) credential = 'app';
+  }
+  if (!token && process.env.GITHUB_PUSH_TOKEN) { token = process.env.GITHUB_PUSH_TOKEN; credential = 'token'; }
   if (!token) return { ok: false, code: 'UNCONFIGURED' };
   const repoInfo = deps.repoInfo || loadRepoInfo();
   if (!repoInfo || repoInfo.error) return { ok: false, code: 'NO_REPO_INFO' };
@@ -35,10 +45,10 @@ async function dispatchWorkflow({ workflow, ref = 'main', inputs = {} }, deps =
       headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
       body: JSON.stringify({ ref, inputs }),
     });
-    if (res.status === 204 || res.ok) return { ok: true };
-    return { ok: false, code: 'REFUSED', status: res.status };
+    if (res.status === 204 || res.ok) return { ok: true, credential };
+    return { ok: false, code: 'REFUSED', status: res.status, credential };
   } catch (_) {
-    return { ok: false, code: 'UNREACHABLE' };
+    return { ok: false, code: 'UNREACHABLE', credential };
   }
 }
 

package/modules/npm-release/release.js

@@ -95,6 +95,15 @@ async function readReleaseLedger(pool) {
   }
 }
 
+// The credential a refusal names, in the words of the settings page the owner must open: GitHub
+// lists an App under Developer settings → GitHub Apps, and an access token under Developer
+// settings → Personal access tokens (task 1004518).
+function credentialName(credential) {
+  if (credential === 'app') return "the server's GitHub App";
+  if (credential === 'token') return "the server's GitHub access token (GITHUB_PUSH_TOKEN, under Developer settings → Personal access tokens)";
+  return "the server's GitHub credential";
+}
+
 /**
  * What the Release button does. Returns { status, body } for the route to send.
  *
@@ -118,7 +127,7 @@ async function requestRelease({ version, registry, dispatch } = {}) {
   }
   const why = !r ? 'no answer'
     : r.code === 'UNCONFIGURED' ? 'this server has no GitHub credential'
-      : r.code === 'REFUSED' && r.status === 403 ? "GitHub refused: the server's GitHub App needs the Actions: write permission"
+      : r.code === 'REFUSED' && r.status === 403 ? `GitHub refused: ${credentialName(r.credential)} needs the Actions: write permission on this repository`
         : r.code === 'REFUSED' && r.status === 404 ? 'GitHub could not find publish.yml, or the App cannot see this repository'
           : r.code === 'REFUSED' ? `GitHub refused the request (${r.status})`
             : r.code === 'UNREACHABLE' ? 'GitHub could not be reached'

package/modules/onboarding/founding-birth.js

@@ -0,0 +1,116 @@
+'use strict';
+
+// modules/onboarding/founding-birth.js — A NEW PROJECT IS BORN INTO GENESIS (task
+// 1004506 / BV2.PS18, goal 1000121; spec docs/specs/bongos-v2-project-startup.md step 5,
+// D4, D8, D9).
+//
+// THE PROBLEM. POST /founding/start existed, but nothing called it, so a project made
+// through the startup flow opened as an ordinary hall. The create request lands on the
+// HUB, while founding mode lives in the NEW INSTANCE's own project_settings, and the hub
+// holds no way into that database. So the hub only says so, and the instance acts:
+//
+//   1. The hub's create route stamps a reserved key on the new row
+//      (modules/provisioning/birth.js) — never on a row that already exists.
+//   2. The runner writes it into the instance's web.env with the other settings
+//      companions: <PREFIX>_FOUNDING_BIRTH, plus <PREFIX>_DEMO_PEOPLE / _DEMO_HOURS
+//      when the row is a demo. src/branding.js maps them onto `founding.*`, which is
+//      server-only (clientBranding never publishes it).
+//   3. Here, the instance reads that marker and, once, starts founding — and for a
+//      demo, also settles the expedited plan, so its decide stage needs no choices.
+//
+// WHEN IT RUNS: lazily, on the first founding read (GET /me through the port, and
+// GET /founding/genesis), not at boot. The first /me is the hall's first paint after the
+// founder's first sign-in, so the hall opens already in genesis; and by then the
+// founder is seated and the kickoff seed has run, so the board the demo's stages are
+// filed on exists. At boot it would race the module load order (the lifecycle port the
+// plan files tasks through may not be registered yet) and a database that is still
+// coming up.
+//
+// WHY IT CANNOT RACE OR TOUCH AN OLD PROJECT.
+//   * No marker, no run: a project created before this shipped has none (D8), and a
+//     marker-less read resolves without touching the database.
+//   * Once per process: one shared promise, so two concurrent first reads share one run.
+//   * Once for good: founding is started only when it was never started and never
+//     ended (founding.started_at / ended_at), so a restart, a later settings push that
+//     rewrites the env, or an owner who already started by hand changes nothing. A demo
+//     carried over keeps its state for the same reason: genesis happened once.
+//   * The demo's plan is saved only while the project is still deciding with no plan,
+//     and savePlan itself refuses outside 'decide'; the stage tasks are filed by a seeder
+//     that skips a step already filed.
+
+const fm = require('./founding-mode');
+const genesis = require('./genesis-home');
+
+// The demo's limits and the bounds check are genesis-home.js's own, never retyped here.
+const { DEMO_PEOPLE, DEMO_HOURS, intIn } = genesis;
+
+// birthMarker(founding) — PURE. The resolved branding pack's `founding` block → whether
+// this project was born through the startup flow, and its demo time box if a demo. A
+// malformed demo value reads as no demo (the project still founds, with the normal plan).
+function birthMarker(founding) {
+  const f = founding && typeof founding === 'object' ? founding : {};
+  const born = typeof f.birth === 'string' && Number.isFinite(new Date(f.birth).getTime());
+  if (!born) return { born: false, demo: null };
+  const people = Number(f.demoPeople);
+  const hours = Number(f.demoHours);
+  const demo = intIn(people, DEMO_PEOPLE[0], DEMO_PEOPLE[1]) && intIn(hours, DEMO_HOURS[0], DEMO_HOURS[1]) ? { people, hours_each: hours } : null;
+  return { born: true, demo };
+}
+
+function markerFrom(deps) {
+  if (deps.marker) return deps.marker;
+  let b;
+  try { b = require('../../src/module-api').branding(); } catch (_) { return { born: false, demo: null }; }
+  return birthMarker(b && b.founding);
+}
+
+// bornFounding(deps) — the guarded birth. Returns what it did:
+//   { ran: false, reason }                       nothing to do (no marker, already, alive)
+//   { ran: true, started, plan, demo }           it started founding and/or saved the plan
+//   { ran: false, reason, retry: true }          the demo plan could not be saved yet
+async function bornFounding(deps = {}) {
+  const marker = markerFrom(deps);
+  if (!marker.born) return { ran: false, reason: 'no_marker' };
+  const get = deps.getSetting || require('../../src/module-api').projectSettings.get;
+  const [started, ended] = await Promise.all([get(fm.KEYS.STARTED_AT), get(fm.KEYS.ENDED_AT)]);
+  if (ended && ended.value) return { ran: false, reason: 'already_alive' };
+  let didStart = false;
+  if (!(started && started.value)) {
+    const r = await genesis.startFounding(null, deps);
+    if (!r.ok) return { ran: false, reason: r.reason };
+    didStart = true;
+  }
+  if (!marker.demo) return didStart ? { ran: true, started: true, plan: false, demo: false } : { ran: false, reason: 'already_started' };
+  // The demo's expedited plan: only while still deciding, and only if none is saved.
+  const mode = await fm.foundingModeFor(genesis.modeDepsFor({ ...deps, getSetting: get }));
+  const planRow = await get(genesis.PLAN_KEY);
+  if (!mode || mode.stage !== 'decide' || (planRow && planRow.value)) {
+    return didStart ? { ran: true, started: true, plan: false, demo: true } : { ran: false, reason: 'already_started' };
+  }
+  const saved = await genesis.savePlan(genesis.demoPlan(marker.demo), null, deps);
+  if (!saved.ok) return { ran: false, reason: saved.reason, retry: true };
+  return { ran: true, started: didStart, plan: true, demo: true };
+}
+
+// ensureBirth(deps) — the once-per-process door the reads call. Shares one run between
+// concurrent callers; forgets a run that failed or asked to retry, so a later read tries
+// again. Never throws: a birth hiccup must never fail the read that triggered it.
+let once = null;
+function ensureBirth(deps = {}) {
+  if (once) return once;
+  const p = bornFounding(deps).then((r) => {
+    if (r && r.retry) once = null;
+    return r;
+  }, (err) => {
+    once = null;
+    try { require('../../src/module-api').logger('onboarding').error('[onboarding] founding birth failed', err); } catch (_) { /* no logger: nothing to do */ }
+    return { ran: false, reason: 'error' };
+  });
+  once = p;
+  return p;
+}
+
+// Test seam: forget the per-process run.
+function resetBirthForTests() { once = null; }
+
+module.exports = { birthMarker, bornFounding, ensureBirth, resetBirthForTests };

package/modules/onboarding/genesis-home.js

@@ -75,7 +75,65 @@ function parsePlan(body = {}) {
   if (government !== null && !/^[a-z][a-z-]{1,39}$/.test(government)) return { ok: false, reason: 'bad_government' };
   const expected = b.expected_builders == null || b.expected_builders === '' ? null : Number(b.expected_builders);
   if (expected !== null && !intIn(expected, 1, 100000)) return { ok: false, reason: 'bad_expected_builders' };
-  return { ok: true, plan: { days, passes, advisors, government, expected_builders: expected, existing: b.existing === true } };
+  const plan = { days, passes, advisors, government, expected_builders: expected, existing: b.existing === true };
+  // A DEMO's plan (task 1004506) also carries its time box and each stage's length in
+  // minutes. Only the birth path writes these (demoPlan below): the plan route's schema
+  // does not name them, so a client cannot send one.
+  if (b.demo != null) {
+    const d = b.demo;
+    if (!d || !intIn(d.people, DEMO_PEOPLE[0], DEMO_PEOPLE[1]) || !intIn(d.hours_each, DEMO_HOURS[0], DEMO_HOURS[1])) return { ok: false, reason: 'bad_demo' };
+    plan.demo = { people: d.people, hours_each: d.hours_each };
+  }
+  if (b.minutes != null) {
+    plan.minutes = {};
+    for (const s of PROPER) {
+      const m = b.minutes[s];
+      if (!intIn(m, 1, MAX_DEMO_MINUTES)) return { ok: false, reason: 'bad_minutes', stage: s };
+      plan.minutes[s] = m;
+    }
+  }
+  return { ok: true, plan };
+}
+
+// ── the demo's expedited genesis (task 1004506) ──────────────────────────────
+// Owner ruling, 2026-10-01: a demo DOES go through genesis, but expedited, because the
+// point of a demo is that the whole thing is fast. So a demo's plan is settled before
+// the founder ever sees it, from what the demo already picked: Monarchy / BDFL (the
+// founder's one yes closes each stage, spec D4's fast-track), one pass, no advisors,
+// the demo's people as the headcount. Its stages are minutes, not days: genesis gets a
+// fifth of the hours each person has (at least ten minutes, at most two hours), split
+// by how much each stage asks, so a small team reaches "come alive" with most of the
+// time box left for building.
+const DEMO_PEOPLE = Object.freeze([1, 12]); // modules/provisioning/demo.js DEMO_LIMITS
+const DEMO_HOURS = Object.freeze([1, 40]);
+const MAX_DEMO_MINUTES = 240;
+const DEMO_SHARE = 0.2;
+const DEMO_GENESIS_MINUTES = Object.freeze([10, 120]);
+const DEMO_WEIGHTS = Object.freeze({ scope: 3, strategize: 2, charter: 2, legalize: 1, legislation: 2 });
+
+// demoMinutes(hoursEach) — PURE. Each stage's length in minutes, from the time box.
+function demoMinutes(hoursEach) {
+  const [lo, hi] = DEMO_GENESIS_MINUTES;
+  const budget = Math.min(hi, Math.max(lo, Math.round(hoursEach * 60 * DEMO_SHARE)));
+  const total = Object.values(DEMO_WEIGHTS).reduce((a, b) => a + b, 0);
+  const out = {};
+  for (const s of PROPER) out[s] = Math.max(1, Math.round((budget * DEMO_WEIGHTS[s]) / total));
+  return out;
+}
+
+// demoPlan({ people, hours_each }) — PURE. The plan body a demo is born with; it goes
+// through parsePlan like any other, so it is held to the same ranges.
+function demoPlan({ people, hours_each: hoursEach }) {
+  return {
+    days: Object.fromEntries(PROPER.map((s) => [s, 1])),
+    minutes: demoMinutes(hoursEach),
+    passes: 1,
+    advisors: 'none',
+    government: 'monarchy',
+    expected_builders: people,
+    existing: false,
+    demo: { people, hours_each: hoursEach },
+  };
 }
 
 function readPlanValue(raw) {
@@ -99,8 +157,11 @@ function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {} }) {
     const list = (tasks[key] || []).map((t) => ({ ...t, finished: FINISHED.includes(t.status) }));
     const b = board[key] || null;
     const days = plan && plan.days && plan.days[key] ? plan.days[key] : info.days;
+    // A demo's stage is minutes long (task 1004506); its due time is counted in them.
+    const minutes = plan && plan.minutes && plan.minutes[key] ? plan.minutes[key] : null;
     const began = stageAt[key] ? new Date(stageAt[key]) : null;
-    const due = began && Number.isFinite(began.getTime()) ? new Date(began.getTime() + days * 86400000).toISOString() : null;
+    const span = minutes ? minutes * 60000 : days * 86400000;
+    const due = began && Number.isFinite(began.getTime()) ? new Date(began.getTime() + span).toISOString() : null;
     return {
       key,
       number: idx,
@@ -110,6 +171,7 @@ function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {} }) {
       done_when: info.done_when,
       wakes: fm.WAKES[key] || [],
       days,
+      minutes,
       due,
       state: idx < at ? 'done' : idx === at ? 'now' : 'later',
       tasks: list,
@@ -131,6 +193,8 @@ function shapeGenesis({ mode, plan, tasks = {}, board = {}, stageAt = {} }) {
     day: mode.day,
     deciding: mode.stage === 'decide',
     plan: plan || null,
+    // The demo's time box when this genesis is a demo's (task 1004506), else null.
+    demo: plan && plan.demo ? plan.demo : null,
     stages,
     // The close door: every task of the current stage finished, and not already sitting.
     can_close: !!(now && now.total > 0 && now.finished === now.total && !sitting && !passed),
@@ -193,8 +257,9 @@ async function readGenesis(deps = {}) {
   return shapeGenesis({ mode, plan, tasks, board, stageAt });
 }
 
-// startFounding — a brand-new project enters genesis (the create flow's birth calls
-// this). Refused once the project has come alive: genesis happens once (spec D8).
+// startFounding — a brand-new project enters genesis (founding-birth.js calls this once
+// on a project born through the startup flow, task 1004506). Refused once the project
+// has come alive: genesis happens once (spec D8).
 async function startFounding(builderId, deps = {}) {
   const s = seams(deps);
   const ended = await s.get(fm.KEYS.ENDED_AT);
@@ -269,6 +334,8 @@ async function onStagePassed(deps = {}) {
 }
 
 module.exports = {
-  PLAN_KEY, STAGE_INFO, PROPER, parsePlan, shapeGenesis,
+  PLAN_KEY, STAGE_INFO, PROPER, DEMO_PEOPLE, DEMO_HOURS, intIn, parsePlan, shapeGenesis, demoMinutes, demoPlan,
   readGenesis, startFounding, savePlan, closeStage, comeAlive, onStagePassed,
+  // the founding-mode deps this file reads the mode with, for founding-birth.js (task 1004506)
+  modeDepsFor: (deps) => modeDeps(seams(deps)),
 };

package/modules/onboarding/port.js

@@ -41,6 +41,7 @@
 const onboardingState = require('./onboarding-state');
 const newcomerRestock = require('./newcomer-restock');
 const foundingMode = require('./founding-mode');
+const foundingBirth = require('./founding-birth');
 
 module.exports = {
   // --- the newcomer onboarding state machine (onboarding-state.js) ---------
@@ -56,8 +57,14 @@ module.exports = {
 
   // --- project founding mode (founding-mode.js, task 1004422) ---------------
   // me.js reads it for the hall shell (null = not founding = the hall as today);
-  // the genesis home (task 1004423) drives the write.
-  foundingModeFor: (...a) => foundingMode.foundingModeFor(...a),
+  // the genesis home (task 1004423) drives the write. A project born through the
+  // startup flow enters genesis on this, its first read (founding-birth.js, task
+  // 1004506): once, guarded, and a no-op without the birth marker. A caller passing
+  // its own deps (a test) skips the birth.
+  foundingModeFor: async (...a) => {
+    if (!a.length) await foundingBirth.ensureBirth();
+    return foundingMode.foundingModeFor(...a);
+  },
   setFoundingMode: (...a) => foundingMode.setFoundingMode(...a),
 
   // --- the evergreen newcomer-chore restock (newcomer-restock.js) ----------

package/modules/onboarding/routes/onboarding.js

@@ -36,6 +36,7 @@ const onboardingPort = require('../port');
 const buildAccessRequestsRouter = require('./access-requests');
 const foundingBuilders = require('../founding-builders');
 const genesis = require('../genesis-home');
+const foundingBirth = require('../founding-birth');
 
 // Register the `onboarding` kernel PORT. See the header + port.js for the full
 // consumer list and the graceful-degradation contract.
@@ -76,6 +77,7 @@ const GENESIS_REFUSALS = {
   not_at_legislation: 409, legislation_not_passed: 409, stage_tasks_unfinished: 409,
   no_stage_tasks: 409, unknown_stage: 400, no_board: 503,
   bad_days: 400, bad_passes: 400, bad_advisors: 400, bad_government: 400, bad_expected_builders: 400,
+  bad_demo: 400, bad_minutes: 400,
 };
 let genesisListening = false;
 
@@ -101,7 +103,12 @@ function mountGenesisRoutes(router) {
       res.status(500).json({ error: { code: 'genesis_failed', message: 'internal error' } });
     }
   };
-  router.get('/founding/genesis', api.requireBuilder, handle(async (req) => ({ genesis: await genesis.readGenesis(), viewer_id: String(req.builder.id) })));
+  // A project born through the startup flow enters genesis on its first founding read
+  // (founding-birth.js, task 1004506) — here and on GET /me through the port.
+  router.get('/founding/genesis', api.requireBuilder, handle(async (req) => {
+    await foundingBirth.ensureBirth();
+    return { genesis: await genesis.readGenesis(), viewer_id: String(req.builder.id) };
+  }));
   router.post('/founding/start', api.requireBuilder, owns, handle((req) => genesis.startFounding(req.builder.id)));
   // The plan's ranges and vocabularies are genesis-home.js parsePlan's (one source);
   // this schema only names the fields so an unknown one is refused.

package/modules/provisioning/birth.js

@@ -0,0 +1,64 @@
+'use strict';
+
+// modules/provisioning/birth.js — the BIRTH MARKER: this project was made through the
+// startup flow, so it is born into genesis (task 1004506 / BV2.PS18; spec
+// docs/specs/bongos-v2-project-startup.md step 5 + D8).
+//
+// Founding mode lives in the NEW INSTANCE's own project_settings, and this process (the
+// hub's web tier) has no way into that database — the one rule of this module. So the
+// hub only says so, and the instance acts on it (modules/onboarding/founding-birth.js):
+//
+//   * the create route stamps `founding_birth` (a reserved settings-jsonb key, like
+//     push_owed and look_accent: platform bookkeeping, out of SETTINGS_VOCAB, so the
+//     settings PATCH cannot write it and effectiveSettings never projects it) on the
+//     row it JUST created — never on one that already existed, so a project made before
+//     this shipped is never born into anything (D8);
+//   * the companions below carry it, and a demo's time box, into the instance's
+//     web.env beside the other settings, at standup and on every settings-apply push.
+//
+// Always emitted, empty meaning "not born through the flow" / "not a demo", for the
+// same reason as every companion: the runner patches these lines in place, and a key
+// that came and went would leave a stale line behind.
+
+const BIRTH_KEY = 'founding_birth';
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+
+const storedOf = (row) => (row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings) ? row.settings : {});
+
+// bornAt(row) — PURE. The birth stamp, or '' for a row that has none (or a mangled one).
+function bornAt(row) {
+  const v = String(storedOf(row)[BIRTH_KEY] || '');
+  return ISO.test(v) && Number.isFinite(new Date(v).getTime()) ? v : '';
+}
+
+// demoBox(row) — PURE. A born demo's { people, hours_each }, or null. Only a row that is
+// both born and a demo carries one: an older demo has no marker and founds nothing.
+function demoBox(row) {
+  if (!bornAt(row)) return null;
+  const d = row && row.demo;
+  if (!d || typeof d !== 'object') return null;
+  const people = Number(d.people);
+  const hours = Number(d.hours_each);
+  if (!Number.isInteger(people) || !Number.isInteger(hours) || people < 1 || hours < 1) return null;
+  return { people, hours_each: hours };
+}
+
+// The companion env (SETTINGS_COMPANION_ENV). src/branding.js maps them onto founding.*.
+const BIRTH_COMPANION_ENV = Object.freeze({
+  FOUNDING_BIRTH: bornAt,
+  DEMO_PEOPLE: (row) => { const d = demoBox(row); return d ? String(d.people) : ''; },
+  DEMO_HOURS: (row) => { const d = demoBox(row); return d ? String(d.hours_each) : ''; },
+});
+
+// stampBirth(db, instanceId, now) — the create route's one write, on the row it just
+// made. Write-once: a stamp already there is kept (the WHERE says so).
+async function stampBirth(db, instanceId, now = new Date()) {
+  await db.query(
+    `UPDATE provisioning_instances
+        SET settings = COALESCE(settings, '{}'::jsonb) || jsonb_build_object($2::text, $3::text)
+      WHERE id = $1 AND NOT (COALESCE(settings, '{}'::jsonb) ? $2::text)`,
+    [instanceId, BIRTH_KEY, now.toISOString()],
+  );
+}
+
+module.exports = { BIRTH_KEY, BIRTH_COMPANION_ENV, stampBirth };

package/modules/provisioning/dns-resolves.js

@@ -0,0 +1,54 @@
+'use strict';
+
+// modules/provisioning/dns-resolves.js — has the platform's own lookup seen this
+// project's address answer? (task 1004505, BV2.PS17; migration provisioning_036)
+//
+// WHY. A visitor's resolver caches a "not found" answer for the zone's negative TTL
+// (cloudbongos.com's SOA minimum is 1800s). The hub used to link an address as soon as
+// the row read 'active', so a founder who clicked before the name answered anywhere
+// could not reach their own project from their home network for up to half an hour.
+// The fix has two halves: the runner creates the DNS record FIRST (scripts/gds/
+// provision.js), and the hub holds every link to the address until `dns_resolves` is
+// true — a fact only a lookup the PLATFORM made can establish, never the status alone.
+//
+// Who writes it: the runner, at the end of a standup (minutes after the record was
+// created, so its own lookup cannot race the record into a cached miss), and the
+// liveness sweep, whose SSRF gate already resolves every active address. Sticky once
+// seen; a changed domain clears it (updateInstanceDomain in ./provisioning.js).
+// Its own file because ./provisioning.js sits at the 1500-line size ratchet.
+
+const dns = require('node:dns').promises;
+
+// The projection publicInstance carries. PURE. No domain ⇒ nothing to resolve.
+function dnsResolves(row) {
+  return !!(row && row.domain && row.dns_resolved_at);
+}
+
+// Record that a lookup answered. Narrow like recordDnsNote: no `status`, no
+// `updated_at`, and only the FIRST sighting writes, so a sweep never rewrites it.
+async function recordDnsResolved(db, id) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_instances SET dns_resolved_at = now()
+      WHERE id = $1 AND dns_resolved_at IS NULL RETURNING id, dns_resolved_at`,
+    [id]
+  );
+  return rows[0] || null;
+}
+
+// One bounded lookup: true when the name resolves to at least one address, false on
+// any failure or after `timeoutMs`. Never throws. `lookup` is injectable for tests.
+async function lookupAnswers(host, { lookup, timeoutMs = 5000 } = {}) {
+  if (!host) return false;
+  let timer = null;
+  const timeout = new Promise((resolve) => { timer = setTimeout(() => resolve(false), timeoutMs); });
+  try {
+    const ask = Promise.resolve((lookup || dns.lookup)(host, { all: true }))
+      .then((addrs) => Array.isArray(addrs) ? addrs.some((a) => a && a.address) : !!(addrs && addrs.address))
+      .catch(() => false);
+    return await Promise.race([ask, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+module.exports = { dnsResolves, recordDnsResolved, lookupAnswers };

package/modules/provisioning/migrations/provisioning_036_dns_resolved.sql

@@ -0,0 +1,30 @@
+-- provisioning_036_dns_resolved.sql — when the platform's own lookup first saw a
+-- project's address answer (task 1004505, BV2.PS17).
+--
+-- WHY THIS EXISTS. A visitor's resolver caches a "not found" answer for the zone's
+-- negative TTL (30 minutes on cloudbongos.com). The hub used to link a project's
+-- address as soon as the row said 'active', and the founder's first click, made
+-- before the name answered anywhere, poisoned their own home network for half an
+-- hour. The hub now holds every link to the address until this column is set.
+--
+-- WHAT IT ADDS.
+--   provisioning_instances.dns_resolved_at — NULL until a lookup made by the
+--   platform (the runner at the end of a standup, or the liveness sweep's gate)
+--   returned an address for the row's domain. Projected as `dns_resolves`.
+--   A changed domain clears it (updateInstanceDomain), like the liveness overlay.
+--
+-- OVERLAY, NOT A STATE (the provisioning_006 rule): nullable, no default, never
+-- written by the lifecycle. The backfill marks every address the sweep has
+-- already seen answer, so no live project loses its link when this lands.
+--
+-- Additive and namespaced (ADR 0083): no down-migration, idempotent — safe to re-run.
+
+BEGIN;
+
+ALTER TABLE provisioning_instances ADD COLUMN IF NOT EXISTS dns_resolved_at timestamptz;
+
+UPDATE provisioning_instances
+   SET dns_resolved_at = last_verified_at
+ WHERE dns_resolved_at IS NULL AND last_verified_up IS TRUE AND domain IS NOT NULL;
+
+COMMIT;