@bongos/core 1.20.82 → 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/done-when.js

@@ -518,42 +518,91 @@ async function autoSatisfyShippedCriteria(exec, { taskId = null, criterionId = n
                c.satisfied_by_task_id`,
     [scopedTaskId, scopedCriterionId]
   );
-  if (criteria.length === 0) return { criteria: [], goals: [] };
+  // THE SHIP THAT FLIPS NO CRITERION STILL FINISHES ITS GOAL (task 1004513).
+  // Returning here unconditionally was a hole. When every criterion of a goal was
+  // satisfied BEFORE its last task shipped, the UPDATE above matches nothing — and
+  // the other writer (`POST /done-when/:id/satisfy` → achieveGoalIfComplete) had
+  // already run too early, while that task was still open, so it correctly held
+  // the goal open and then nobody ever re-asked. The goal sat `open` with every
+  // criterion satisfied and no work left, until a criterion was satisfied a second
+  // time purely to re-trigger the other door.
+  //
+  // So on the SCOPED ship path, re-check the shipping task's OWN goal against the
+  // same rule the cascade below applies. `exec` is load-bearing here for the same
+  // reason it is there: this task's flip to `shipped` is uncommitted, and on the
+  // module pool the task check would still read `confirmed` — non-terminal — and
+  // hold the goal open exactly as before.
+  //
+  // The UNSCOPED sweep keeps its cheap early return: it holds no task, so there is
+  // no candidate goal to name, and every goal it can close it closes through the
+  // cascade below.
+  if (criteria.length === 0) {
+    if (scopedTaskId == null) return { criteria: [], goals: [] };
+    const { rows: own } = await exec.query(
+      `SELECT goal_id FROM tasks WHERE id = $1::bigint AND goal_id IS NOT NULL`,
+      [scopedTaskId]
+    );
+    const goals = await achieveCompletedGoals(exec, own.map((r) => Number(r.goal_id)));
+    return { criteria: [], goals, versionsClosed: await autoCloseVersionsForGoals(exec, goals) };
+  }
 
   // Cascade. Deliberately re-derived from the table rather than from `criteria`:
   // a goal completes when ALL of its criteria are satisfied, and the ones that
-  // closed in THIS call may not be all of them. Mirrors db.achieveGoalIfComplete
-  // exactly — open goals only, >=1 criterion, zero unsatisfied, AND no unfinished
-  // task (BV1.R09, task 1003596) — but on `exec`, so it sees the flips above
-  // inside the same transaction.
-  //
-  // THE THIRD CLAUSE, and why it must run HERE and not only in db-goals.js. This
-  // is the path that actually fires on every ship (`db-ship.js`) and every
-  // reconciler tick (`publish-reconciler.js`); `achieveGoalIfComplete` covers the
-  // manual `POST /done-when/:id/satisfy`. The two are a DELIBERATE duplicate —
-  // collapsing them into one helper creates a require cycle (db-goals requires
-  // done-when) — so the rule is written twice on purpose and both copies must
-  // move together, or a goal closes correctly through one door and wrongly
-  // through the other. ADR 0250 D2.
-  //
-  // `exec` is load-bearing for THIS clause specifically. The shipping task's flip
-  // to `shipped` is uncommitted at this point in the ship transaction; on the
-  // module pool the subquery would still see it as `confirmed` — non-terminal —
-  // and refuse to close a goal whose last task just landed. Every goal would then
-  // need a second, later trigger to close at all.
-  //
-  // Shipping is NOT blocked by any of this: the ship's own writes are untouched
-  // and this UPDATE simply matches no row, leaving the goal open.
-  //
-  // The subquery is index-served: migration 228 added idx_tasks_goal ON tasks
-  // (goal_id), so this is a small index scan per candidate goal, and the candidate
-  // set is only the goals whose criteria just closed in this call. (Raised in
-  // review off docs/architecture.md, whose tasks index list predated 228 and has
-  // been corrected.)
+  // closed in THIS call may not be all of them. The statement itself is
+  // achieveCompletedGoals, below.
   const goalIds = [...new Set(criteria.map((c) => c.goal_id).filter((g) => g != null))].map(Number);
   // No goal achieved, so no version can have just become closable.
   if (goalIds.length === 0) return { criteria, goals: [], versionsClosed: [] };
-  const { rows: goals } = await exec.query(
+  const goals = await achieveCompletedGoals(exec, goalIds);
+  // BV1.R16 (task 1003603, ADR 0263 §§3–4): a version closes ITSELF once its last
+  // non-maintenance goal achieves. On the caller's `exec`, so it sees the flips
+  // above that have not committed yet — a check on the pool would never close the
+  // version on the ship that actually finished it.
+  //
+  // `autoCloseVersionsForGoals` catches per version and never rethrows: a version
+  // close must not be able to fail a builder's ship. The accepted failure is a
+  // version left un-closed, which the reconciler's next unscoped sweep heals.
+  const versionsClosed = await autoCloseVersionsForGoals(exec, goals);
+  return { criteria, goals, versionsClosed };
+}
+
+// achieveCompletedGoals — the ONE statement that flips a goal open→achieved on
+// the ship/sweep side. Written once because autoSatisfyShippedCriteria now enters
+// it from two places — the criteria this call just closed, and (task 1004513) the
+// shipping task's own goal when it closed none — and two copies of this rule
+// would be two things to keep in step. Takes the caller's `exec` and the candidate
+// goal ids; returns the rows that actually flipped (usually none).
+//
+// Mirrors db.achieveGoalIfComplete exactly — open goals only, >=1 criterion, zero
+// unsatisfied, AND no unfinished task (BV1.R09, task 1003596).
+//
+// THE THIRD CLAUSE, and why it must run HERE and not only in db-goals.js. This is
+// the path that actually fires on every ship (`db-ship.js`) and every reconciler
+// tick (`publish-reconciler.js`); `achieveGoalIfComplete` covers the manual
+// `POST /done-when/:id/satisfy`. The two are a DELIBERATE duplicate — collapsing
+// them into one helper creates a require cycle (db-goals requires done-when) — so
+// the rule is written twice on purpose and both copies must move together, or a
+// goal closes correctly through one door and wrongly through the other. ADR 0250
+// D2.
+//
+// `exec` is load-bearing for THIS clause specifically. The shipping task's flip
+// to `shipped` is uncommitted at this point in the ship transaction; on the module
+// pool the subquery would still see it as `confirmed` — non-terminal — and refuse
+// to close a goal whose last task just landed. Every goal would then need a
+// second, later trigger to close at all.
+//
+// Shipping is NOT blocked by any of this: the ship's own writes are untouched and
+// this UPDATE simply matches no row, leaving the goal open.
+//
+// The subquery is index-served: migration 228 added idx_tasks_goal ON tasks
+// (goal_id), so this is a small index scan per candidate goal, and the candidate
+// set is only the goals this call could possibly have completed. (Raised in review
+// off docs/architecture.md, whose tasks index list predated 228 and has been
+// corrected.)
+async function achieveCompletedGoals(exec, goalIds) {
+  const ids = (goalIds || []).filter((g) => g != null).map(Number);
+  if (ids.length === 0) return [];
+  const { rows } = await exec.query(
     `UPDATE goals g
         SET status = 'achieved', updated_at = now()
       WHERE g.id = ANY($1::bigint[])
@@ -564,21 +613,12 @@ async function autoSatisfyShippedCriteria(exec, { taskId = null, criterionId = n
                           AND ${nonTerminalSql()}
                           AND ${SMOKE_NOT_LIKE.replace(/title/, 't.title')})
      RETURNING g.id, g.title, g.version_id, g.status`,
-    [goalIds]
+    [ids]
   );
   // Task 1003660: an achieved goal takes no new members — close its pending asks
   // on the same executor, so the cancel rides the ship transaction.
-  await cancelPendingMembershipRequests(exec, goals.map((g) => g.id));
-  // BV1.R16 (task 1003603, ADR 0263 §§3–4): a version closes ITSELF once its last
-  // non-maintenance goal achieves. On the caller's `exec`, so it sees the flips
-  // above that have not committed yet — a check on the pool would never close the
-  // version on the ship that actually finished it.
-  //
-  // `autoCloseVersionsForGoals` catches per version and never rethrows: a version
-  // close must not be able to fail a builder's ship. The accepted failure is a
-  // version left un-closed, which the reconciler's next unscoped sweep heals.
-  const versionsClosed = await autoCloseVersionsForGoals(exec, goals);
-  return { criteria, goals, versionsClosed };
+  await cancelPendingMembershipRequests(exec, rows.map((g) => g.id));
+  return rows;
 }
 
 // describeAutoClose — the one-line summary of what a close actually closed, or

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.