@bongos/core 1.20.83 → 1.21.1

package/scripts/gds/session-transcript-build.js

@@ -0,0 +1,155 @@
+// scripts/gds/session-transcript-build.js — the PURE transcript→full-transcript builder.
+//
+// ADR 0051 / task 1001004: every session is stored as its FULL per-turn content
+// (user prompts, assistant text, tool calls AND their results), not just the
+// metadata + 160-char snippets buildSessionDigest keeps. This is the sibling of
+// session-digest-build.js and shares its scrubber: EVERY string leaves this file
+// through scrubSecrets (modules/security/secret-scrub.js, the task-1003 scrubber),
+// on the builder's box, before anything is uploaded. A string that reaches the
+// output unscrubbed is a defect — keep that single choke point (`clean`).
+//
+// Bounded on purpose: each text field is capped and the whole transcript has a
+// byte ceiling (head + tail kept, like buildSessionDigest's turn cap), so one
+// runaway tool result cannot make an upload that the server must reject.
+// Extended-thinking blocks are NOT captured: they are model-internal, often
+// opaque, and ADR 0051 asks for what the builder asked and what they were told.
+const { scrubSecrets } = require('../../modules/security/secret-scrub');
+
+const MAX_FIELD_CHARS = 20000;          // one prompt / reply / tool result / tool input
+const MAX_TRANSCRIPT_BYTES = 12 * 1024 * 1024; // whole upload ceiling (the server enforces the same number)
+const MAX_TRANSCRIPT_TURNS = 20000;            // the route's maxItems; the builder trims to it so the server never has to refuse
+const MAX_TURN_BYTES = 200 * 1024;            // under the route's 256 KB per-turn cap, so a many-tool-call turn is shrunk here rather than refused there
+const MAX_RAW_CHARS = 200000;                  // bound on what the scrubber is ever handed (entropy-sweep cost)
+
+// clean — the one exit for every string: drop NULs (Postgres rejects them in
+// jsonb), SCRUB, then cap. Scrub BEFORE the final cap so a credential straddling
+// the cap boundary is redacted whole rather than sliced into a fragment too short
+// for any scrub shape to recognise. The scrubber is only ever handed MAX_RAW_CHARS
+// so a multi-MB tool result cannot make the entropy sweep unbounded.
+function clean(text, extraSecrets) {
+  if (typeof text !== 'string' || text.length === 0) return undefined;
+  const flat = text.replace(/\0/g, '');
+  if (!flat) return undefined;
+  const bounded = flat.length > MAX_RAW_CHARS ? flat.slice(0, MAX_RAW_CHARS) : flat;
+  const scrubbed = scrubSecrets(bounded, extraSecrets);
+  if (!scrubbed) return undefined;
+  if (scrubbed.length <= MAX_FIELD_CHARS && flat.length === bounded.length) return scrubbed;
+  const omitted = (flat.length - bounded.length) + Math.max(0, scrubbed.length - MAX_FIELD_CHARS);
+  return `${scrubbed.slice(0, MAX_FIELD_CHARS)}…[+${omitted} chars]`;
+}
+
+function resultText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content.map((p) => (p && typeof p.text === 'string' ? p.text : '')).filter(Boolean).join('\n');
+  }
+  return '';
+}
+
+// shrinkTurn — cut every string field of an oversize turn to an even share of a
+// fixed character budget (in place), marking the cut. Already scrubbed, so this
+// only ever removes text.
+function shrinkTurn(t) {
+  const fields = [];
+  if (typeof t.text === 'string') fields.push([t, 'text']);
+  for (const c of t.tool_calls || []) if (typeof c.input === 'string') fields.push([c, 'input']);
+  for (const r of t.tool_results || []) if (typeof r.text === 'string') fields.push([r, 'text']);
+  const cap = Math.max(200, Math.floor(40000 / Math.max(1, fields.length)));
+  for (const [o, k] of fields) {
+    if (o[k].length > cap) o[k] = `${o[k].slice(0, cap)}…[+${o[k].length - cap} chars]`;
+  }
+}
+
+// buildSessionTranscript — parsed Claude Code transcript entries →
+// { turns, turnCount, byteSize, truncated }. Pure; exported for tests.
+function buildSessionTranscript(entries, opts = {}) {
+  const extra = opts.extraSecrets || [];
+  const maxBytes = opts.maxBytes || MAX_TRANSCRIPT_BYTES;
+  const maxTurns = opts.maxTurns || MAX_TRANSCRIPT_TURNS;
+  const turns = [];
+  let i = 0;
+  for (const e of Array.isArray(entries) ? entries : []) {
+    if (!e || typeof e !== 'object' || !e.message) continue;
+    const ts = typeof e.timestamp === 'string' ? e.timestamp : undefined;
+    const msg = e.message;
+    if (e.type === 'assistant') {
+      const row = { i, role: 'assistant', ts };
+      const texts = [];
+      const calls = [];
+      for (const c of Array.isArray(msg.content) ? msg.content : []) {
+        if (c && c.type === 'text' && typeof c.text === 'string') texts.push(c.text);
+        else if (c && c.type === 'tool_use') {
+          let input;
+          try { input = clean(JSON.stringify(c.input), extra); } catch (_) { input = undefined; }
+          calls.push({ name: String(c.name || '?'), input });
+        }
+      }
+      const text = clean(texts.join('\n'), extra);
+      if (text) row.text = text;
+      if (calls.length) row.tool_calls = calls;
+      if (!text && !calls.length) continue; // pure-thinking line: nothing readable
+      turns.push(row);
+      i++;
+    } else if (e.type === 'user') {
+      const row = { i, role: 'user', ts };
+      if (typeof msg.content === 'string') {
+        const text = clean(msg.content, extra);
+        if (text) row.text = text;
+      } else if (Array.isArray(msg.content)) {
+        const texts = [];
+        const results = [];
+        for (const c of msg.content) {
+          if (c && c.type === 'text' && typeof c.text === 'string') texts.push(c.text);
+          else if (c && c.type === 'tool_result') {
+            const r = { text: clean(resultText(c.content), extra) };
+            if (c.is_error) r.is_error = true;
+            results.push(r);
+          }
+        }
+        const text = clean(texts.join('\n'), extra);
+        if (text) row.text = text;
+        if (results.length) row.tool_results = results;
+      }
+      if (!row.text && !row.tool_results) continue;
+      turns.push(row);
+      i++;
+    }
+  }
+
+  // Byte ceiling: keep the head (what was asked) and the tail (how it ended),
+  // drop the middle, and SAY so — a silently shortened record reads as complete.
+  // Serialize each turn once; an oversize turn (many tool calls, each at the field
+  // cap) is shrunk field-by-field to fit, so the route's per-turn cap never refuses
+  // a transcript the builder could have trimmed. Sizes include the comma each turn
+  // costs in the array, and the total the 2 bytes of brackets, so this total is the
+  // SAME number the route measures against its ceiling.
+  const sizes = turns.map((t, idx) => {
+    let json = JSON.stringify(t);
+    let bytes = Buffer.byteLength(json, 'utf8');
+    if (bytes > MAX_TURN_BYTES) {
+      shrinkTurn(t);
+      json = JSON.stringify(t);
+      bytes = Buffer.byteLength(json, 'utf8');
+    }
+    turns[idx] = t;
+    return bytes + 1;
+  });
+  let total = sizes.reduce((a, b) => a + b, 2);
+  let out = turns;
+  let truncated = false;
+  if (total > maxBytes || turns.length > maxTurns) {
+    truncated = true;
+    const headBudget = Math.floor(maxBytes * 0.6);
+    const tailBudget = maxBytes - headBudget;
+    let h = 0; let headEnd = 0;
+    const headCount = Math.floor(maxTurns * 0.6);
+    while (headEnd < turns.length && headEnd < headCount && h + sizes[headEnd] <= headBudget) h += sizes[headEnd++];
+    let t = 0; let tailStart = turns.length;
+    while (tailStart > headEnd && (turns.length - tailStart) < maxTurns - headEnd && t + sizes[tailStart - 1] <= tailBudget) t += sizes[--tailStart];
+    out = turns.slice(0, headEnd).concat(turns.slice(tailStart));
+    total = h + t + 2;
+  }
+  return { turns: out, turnCount: turns.length, byteSize: total, truncated };
+}
+
+module.exports = { buildSessionTranscript, MAX_FIELD_CHARS, MAX_TRANSCRIPT_BYTES, MAX_TRANSCRIPT_TURNS };

package/scripts/gds/session-transcript-upload.js

@@ -0,0 +1,29 @@
+// scripts/gds/session-transcript-upload.js — send a session's FULL scrubbed
+// transcript to the corpus (ADR 0051, task 1001004).
+//
+// Shared by the SessionEnd hook (session-digest.js — fires for EVERY session) and
+// the on-ship upload (ship-session-upload.js — covers the mid-session tail), so
+// both build and send the transcript the same way. BEST-EFFORT and NON-FATAL like
+// the digest upload beside it: returns a one-line outcome string, never throws.
+// It must run AFTER the digest POST — the server creates the transcript row only
+// from the caller's own session_records row.
+const { buildSessionTranscript } = require('./session-transcript-build');
+
+async function uploadSessionTranscript(api, sessionId, entries, extraSecrets) {
+  try {
+    const t = buildSessionTranscript(entries, { extraSecrets });
+    if (!t.turns.length) return 'transcript: nothing to store.';
+    const r = await api.sessions.putSessionsSidTranscript({
+      sid: sessionId,
+      body: { turns: t.turns, truncated: t.truncated },
+    });
+    if (r && r.ok) {
+      return `transcript: stored ${t.turns.length}/${t.turnCount} turns (${Math.round(t.byteSize / 1024)} KB${t.truncated ? ', truncated to the size ceiling' : ''}).`;
+    }
+    return `transcript: skipped (PUT ${r && r.status}${r && r.data && r.data.error ? ' ' + JSON.stringify(r.data.error) : ''}).`;
+  } catch (e) {
+    return `transcript: skipped — ${e && e.message ? e.message : e}`;
+  }
+}
+
+module.exports = { uploadSessionTranscript };

package/scripts/gds/ship-session-upload.js

@@ -13,6 +13,7 @@ const path = require('node:path');
 const { cliClient, loadSession } = require('./cli-lib');
 const { resolveTranscriptPath } = require('./ship-memory-sync.js');
 const { apiErrorLine } = require('./ship-io.js');
+const { uploadSessionTranscript } = require('./session-transcript-upload.js');
 const { REPO_ROOT } = require('./ship-state.js');
 
 // ---------- Session upload-on-ship (6D.1 / ADR 0027) ----------
@@ -268,11 +269,15 @@ async function uploadSessionOnShip(taskId) {
       metrics: digest.metrics,
       model_usage: digest.metrics.model_usage || {}, // per-model tokens → cost-plus reward (task 1005)
     };
-    const r = await (await cliClient({ allowUnauthenticated: true })).sessions.postSessions({ body: payload });
+    const api = await cliClient({ allowUnauthenticated: true });
+    const r = await api.sessions.postSessions({ body: payload });
     if (r.ok) {
       console.log(
         `  session upload: stored digest (${digest.metrics.assistant_turns} assistant turns, ${digest.totalTokens} tokens, ${digest.metrics.tool_error_count} tool errors, ${digest.metrics.harness_retry_count} harness retries).`
       );
+      // ADR 0051: the full scrubbed transcript rides after the digest (the server
+      // creates it from the digest's row). Non-fatal — its outcome is a log line.
+      console.log(`  session upload: ${await uploadSessionTranscript(api, sessionId, entries, extraSecrets)}`);
     } else if (r.status === 401) {
       recordUploadSkip(taskId, {
         code: 'session_invalid',

package/scripts/gds/upgrade-commit-identity.js

@@ -0,0 +1,32 @@
+'use strict';
+
+// scripts/gds/upgrade-commit-identity.js — WHO the pin commit is signed by when the project's
+// git names nobody (task 1004514). Kept out of upgrade.js, which sits at the 1500-line cap.
+//
+// THE BUG. persistPin staged the new pin and ran `git commit`. In a repo with no
+// user.name/user.email — none in the repo, none global for the account the upgrade runs as —
+// git refuses ("Please tell me who you are"), so the move reported success with the pin
+// STAGED but never committed. The next move then read its own leftovers as a dirty tree and
+// spent its one automatic fix (wedge-remedy.js) committing them. Seen live on 2026-10-01: a
+// throwaway hosted project on cloudbongos.com, and hermeslines-marketing, whose repo carries no
+// identity while every scaffolded one does (provision-repo.js sets it at scaffold time).
+//
+// THE FIX IS A FALLBACK, NEVER AN OVERRIDE. A repo or account that names someone keeps
+// signing as them. Only an empty answer gets the provisioner's own identity, the one the
+// scaffold commits as, through git's AUTHOR/COMMITTER env — so nothing is written into the
+// owner's git config, and the argv stays exactly what it was.
+
+/**
+ * Env for `git commit` in `instanceDir`: null when git already names a committer there, else
+ * the provisioner's identity. Asks git itself, so repo, global and system config all count.
+ */
+function commitIdentityEnv(instanceDir, run, env = process.env) {
+  const r = run('git', ['config', 'user.email'], { cwd: instanceDir, encoding: 'utf8' });
+  if (r && !r.error && r.status === 0 && String(r.stdout || '').trim()) return null;
+  if (env.GIT_AUTHOR_EMAIL || env.GIT_COMMITTER_EMAIL) return null;   // the caller already chose
+  const { provisionerBotName, provisionerBotEmail } = require('./instance-apex.js');
+  const name = provisionerBotName(), email = provisionerBotEmail(env);
+  return { ...env, GIT_AUTHOR_NAME: name, GIT_AUTHOR_EMAIL: email, GIT_COMMITTER_NAME: name, GIT_COMMITTER_EMAIL: email };
+}
+
+module.exports = { commitIdentityEnv };

package/scripts/gds/upgrade.js

@@ -352,7 +352,7 @@ function persistPin({ instanceDir, fromVersion, toVersion, commitPin, push = tru
     err('  ! could not stage the pin files — commit + push them by hand or the next deploy reverts this bump.');
     return { applicable: true, committed: false, pushed: false, dirty, error: 'git add failed' };
   }
-  const commit = run('git', ['commit', '-m', message], { cwd: instanceDir, encoding: 'utf8' });
+  const idEnv = require('./upgrade-commit-identity').commitIdentityEnv(instanceDir, run), commit = run('git', ['commit', '-m', message], { cwd: instanceDir, encoding: 'utf8', ...(idEnv ? { env: idEnv } : {}) }); // a repo naming nobody still commits (task 1004514)
   if (!commit || commit.error || commit.status !== 0) {
     err('  ! could not commit the pin — commit + push it by hand or the next deploy reverts this bump.');
     return { applicable: true, committed: false, pushed: false, dirty, error: 'git commit failed' };

package/src/bongos/routes.js

@@ -93,6 +93,9 @@ function buildGdsRouter() {
     if (
       req.path === '/memory/sync' ||
       req.path === '/sessions' ||
+      // ADR 0051 / task 1001004: the full-transcript upload (MB-scale), which
+      // mounts its own 16 MB parser in modules/sessions/routes/sessions.js.
+      /^\/sessions\/[A-Za-z0-9_-]+\/transcript$/.test(req.path) ||
       req.path === '/llm-cache/store' ||
       /^\/tasks\/\d+\/publish-branch$/.test(req.path) ||
       // task 1003109: the ship-time task visual — a base64 image up to ~5.3 MB

package/src/branding.js

@@ -94,6 +94,15 @@ const ENV_OVERRIDES = [
   ['NIGHT_TINT', ['project', 'nightTint']],
   ['LOOK_ACCENT', ['project', 'lookAccent']],
   ['LOGO_URL', ['project', 'logoUrl']],
+  // The birth marker (task 1004506): set by the platform only on a project created
+  // through the startup flow, so a project made before that never has it (spec D8).
+  // FOUNDING_BIRTH is when the platform made the row; DEMO_PEOPLE / DEMO_HOURS are the
+  // demo's time box, empty for a real project. The onboarding module reads them once to
+  // start genesis (modules/onboarding/founding-birth.js). SERVER-ONLY: clientBranding
+  // publishes no `founding` block.
+  ['FOUNDING_BIRTH', ['founding', 'birth']],
+  ['DEMO_PEOPLE', ['founding', 'demoPeople']],
+  ['DEMO_HOURS', ['founding', 'demoHours']],
 ];
 
 const isObj = (v) => v && typeof v === 'object' && !Array.isArray(v);

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.83'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.1'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/founding_birth.mjs

@@ -0,0 +1,200 @@
+// tests/founding_birth.mjs — A NEW PROJECT IS BORN INTO GENESIS, and a demo's genesis is
+// expedited (task 1004506 / BV2.PS18, goal 1000121; spec step 5, D4, D8, D9).
+//
+// Done-when: a new real project and a new demo each open their hall already in genesis;
+// the demo's decide stage needs no choices and its stages fit its time box; a
+// pre-existing hall is unchanged. These tests RUN the instance half
+// (modules/onboarding/founding-birth.js) over an in-memory project_settings store and
+// fake lifecycle port: the birth hook runs once, is idempotent, never runs without the
+// marker, and never after the project came alive. The hub half (the marker on the row
+// and in web.env) is pinned in tests/provisioning_settings_env.mjs and
+// tests/wizard_demo.mjs.
+//
+// Run:  node --test tests/founding_birth.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const birth = require('../modules/onboarding/founding-birth.js');
+const gh = require('../modules/onboarding/genesis-home.js');
+const fm = require('../modules/onboarding/founding-mode.js');
+
+const BORN = { born: true, demo: null };
+const BORN_DEMO = { born: true, demo: { people: 3, hours_each: 4 } };
+
+function world({ marker = BORN, settings = {}, withLifecycle = true } = {}) {
+  const store = new Map(Object.entries(settings));
+  const writes = [];
+  let seeds = 0;
+  const lifecycle = withLifecycle ? {
+    seedGenesis: async () => { seeds += 1; return { seeded: 5 }; },
+    genesisTasks: async () => ({}),
+  } : null;
+  const deps = () => ({
+    marker,
+    getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+    setSetting: async (k, v) => { writes.push(k); store.set(k, String(v)); return { key: k, value: String(v) }; },
+    lifecycle, government: null, now: new Date('2026-10-01T09:00:00Z'),
+  });
+  return { store, writes, deps, seeds: () => seeds };
+}
+
+// ── the marker ───────────────────────────────────────────────────────────────
+
+test('the marker: born only with a readable birth stamp; a demo box only inside its limits', () => {
+  assert.deepEqual(birth.birthMarker(undefined), { born: false, demo: null });
+  assert.deepEqual(birth.birthMarker({}), { born: false, demo: null });
+  assert.deepEqual(birth.birthMarker({ birth: 'whenever' }), { born: false, demo: null });
+  assert.deepEqual(birth.birthMarker({ birth: '2026-10-01T00:00:00.000Z' }), { born: true, demo: null });
+  assert.deepEqual(birth.birthMarker({ birth: '2026-10-01T00:00:00.000Z', demoPeople: '3', demoHours: '4' }),
+    { born: true, demo: { people: 3, hours_each: 4 } });
+  assert.deepEqual(birth.birthMarker({ birth: '2026-10-01T00:00:00.000Z', demoPeople: '99', demoHours: '4' }),
+    { born: true, demo: null }, 'a malformed box still founds, with the ordinary plan');
+  assert.deepEqual(birth.birthMarker({ demoPeople: '3', demoHours: '4' }), { born: false, demo: null },
+    'a demo box without a birth is not a birth');
+});
+
+// ── the birth hook ───────────────────────────────────────────────────────────
+
+test('no marker: nothing runs, and the database is never read (a pre-existing hall is unchanged)', async () => {
+  const r = await birth.bornFounding({
+    marker: { born: false, demo: null },
+    getSetting: async () => { throw new Error('read without a marker'); },
+    setSetting: async () => { throw new Error('write without a marker'); },
+  });
+  assert.deepEqual(r, { ran: false, reason: 'no_marker' });
+});
+
+test('a new real project is born deciding: founding on, stage decide, no plan, nothing filed', async () => {
+  const w = world();
+  const r = await birth.bornFounding(w.deps());
+  assert.deepEqual(r, { ran: true, started: true, plan: false, demo: false });
+  const mode = await fm.foundingModeFor({ getSetting: w.deps().getSetting, government: null });
+  assert.equal(mode.active, true);
+  assert.equal(mode.stage, 'decide');
+  assert.equal(w.store.get(gh.PLAN_KEY), undefined, 'a real founder settles their own plan');
+  assert.equal(w.seeds(), 0);
+});
+
+test('idempotent: a second run (a restart, a settings push) changes nothing', async () => {
+  const w = world();
+  await birth.bornFounding(w.deps());
+  const before = new Map(w.store);
+  w.writes.length = 0;
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_started' });
+  assert.deepEqual(w.writes, [], 'no write at all');
+  assert.deepEqual([...w.store], [...before]);
+});
+
+test('never after the project came alive: genesis happens once', async () => {
+  const w = world({ settings: {
+    [fm.KEYS.ACTIVE]: 'false', [fm.KEYS.STARTED_AT]: '2026-09-01T00:00:00.000Z', [fm.KEYS.ENDED_AT]: '2026-09-10T00:00:00.000Z',
+  } });
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_alive' });
+  assert.deepEqual(w.writes, []);
+  assert.equal(await fm.foundingModeFor({ getSetting: w.deps().getSetting, government: null }), null, 'the hall stays alive');
+});
+
+test('a founding already under way (started by hand, mid-stage) is left exactly where it is', async () => {
+  const w = world({ marker: BORN_DEMO, settings: {
+    [fm.KEYS.ACTIVE]: 'true', [fm.KEYS.STAGE]: 'strategize', [fm.KEYS.STARTED_AT]: '2026-09-28T00:00:00.000Z',
+  } });
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_started' });
+  assert.deepEqual(w.writes, []);
+  assert.equal(w.seeds(), 0);
+});
+
+test('a new demo is born past decide: the plan is settled from the demo, and its stages are filed', async () => {
+  const w = world({ marker: BORN_DEMO });
+  const r = await birth.bornFounding(w.deps());
+  assert.deepEqual(r, { ran: true, started: true, plan: true, demo: true });
+  assert.equal(w.seeds(), 1, 'the five stages filed as tasks, once');
+  const plan = JSON.parse(w.store.get(gh.PLAN_KEY));
+  assert.equal(plan.government, 'monarchy', 'Monarchy / BDFL: the founder\'s one yes closes each stage (D4)');
+  assert.equal(plan.passes, 1);
+  assert.equal(plan.advisors, 'none');
+  assert.equal(plan.expected_builders, 3, 'the demo\'s people');
+  assert.deepEqual(plan.demo, { people: 3, hours_each: 4 });
+  const mode = await fm.foundingModeFor({ getSetting: w.deps().getSetting, government: null });
+  assert.equal(mode.stage, 'scope', 'the decide stage needs no choices: it is already behind');
+  // Again: nothing more.
+  w.writes.length = 0;
+  assert.deepEqual(await birth.bornFounding(w.deps()), { ran: false, reason: 'already_started' });
+  assert.deepEqual(w.writes, []);
+  assert.equal(w.seeds(), 1, 'never filed twice');
+});
+
+test('a demo whose plan could not be saved yet (no board) asks for a retry, and the retry settles it', async () => {
+  birth.resetBirthForTests();
+  const store = new Map();
+  let seeds = 0;
+  const base = {
+    marker: BORN_DEMO,
+    getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+    setSetting: async (k, v) => { store.set(k, String(v)); },
+    government: null,
+  };
+  const first = await birth.ensureBirth({ ...base, lifecycle: null });
+  assert.equal(first.retry, true);
+  assert.equal(first.reason, 'no_board');
+  assert.equal(store.get(fm.KEYS.STAGE) || 'decide', 'decide');
+  const second = await birth.ensureBirth({ ...base, lifecycle: { seedGenesis: async () => { seeds += 1; return { seeded: 5 }; } } });
+  assert.deepEqual(second, { ran: true, started: false, plan: true, demo: true }, 'the retry saves the plan without restarting founding');
+  assert.equal(seeds, 1);
+  assert.equal(store.get(fm.KEYS.STAGE), 'scope');
+  birth.resetBirthForTests();
+});
+
+test('once per process: concurrent first reads share ONE run', async () => {
+  birth.resetBirthForTests();
+  const w = world({ marker: BORN_DEMO });
+  const results = await Promise.all([birth.ensureBirth(w.deps()), birth.ensureBirth(w.deps()), birth.ensureBirth(w.deps())]);
+  assert.equal(results[0], results[1]);
+  assert.equal(results[1], results[2]);
+  assert.equal(w.seeds(), 1);
+  assert.equal(w.writes.filter((k) => k === fm.KEYS.STARTED_AT).length, 1, 'started once');
+  assert.equal(w.writes.filter((k) => k === gh.PLAN_KEY).length, 1, 'planned once');
+  // A later read reuses the settled run; it does not touch the store again.
+  w.writes.length = 0;
+  await birth.ensureBirth(w.deps());
+  assert.deepEqual(w.writes, []);
+  birth.resetBirthForTests();
+});
+
+test('a run that throws is forgotten, so a later read tries again; the read itself never fails', async () => {
+  birth.resetBirthForTests();
+  let fail = true;
+  const store = new Map();
+  const deps = {
+    marker: BORN,
+    getSetting: async (k) => { if (fail) throw new Error('db down'); return store.has(k) ? { value: store.get(k) } : null; },
+    setSetting: async (k, v) => { store.set(k, String(v)); },
+  };
+  assert.deepEqual(await birth.ensureBirth(deps), { ran: false, reason: 'error' });
+  fail = false;
+  assert.equal((await birth.ensureBirth(deps)).ran, true);
+  assert.equal(store.get(fm.KEYS.ACTIVE), 'true');
+  birth.resetBirthForTests();
+});
+
+// ── the wiring ───────────────────────────────────────────────────────────────
+
+test('the /me read (the port, no arguments) runs the birth first; a caller with its own deps does not', async () => {
+  const port = require('../modules/onboarding/port.js');
+  const orig = { ensure: birth.ensureBirth, read: fm.foundingModeFor };
+  const calls = [];
+  birth.ensureBirth = async () => { calls.push('birth'); };
+  fm.foundingModeFor = async (d) => { calls.push(d ? 'read:deps' : 'read'); return null; };
+  try {
+    await port.foundingModeFor();
+    assert.deepEqual(calls, ['birth', 'read'], 'the birth lands before the read, so the first hall paint is already founding');
+    calls.length = 0;
+    await port.foundingModeFor({ getSetting: async () => null });
+    assert.deepEqual(calls, ['read:deps']);
+  } finally {
+    birth.ensureBirth = orig.ensure;
+    fm.foundingModeFor = orig.read;
+  }
+});

package/tests/founding_mode.mjs

@@ -278,7 +278,9 @@ test('/me carries founding_mode from the onboarding port, fail-open to null', ()
   assert.match(ME, /onboarding\.foundingModeFor\(\)/);
   const at = ME.indexOf('onboarding.foundingModeFor()');
   assert.match(ME.slice(at, at + 200), /catch \(_\) \{ return null; \}/);
-  assert.match(PORT, /foundingModeFor: \(\.\.\.a\) => foundingMode\.foundingModeFor\(\.\.\.a\)/);
+  // The port delegates at call time; a no-argument read (me.js) first runs the guarded
+  // birth (task 1004506, tests/founding_birth.mjs).
+  assert.match(PORT, /foundingModeFor: async \(\.\.\.a\) => \{\s*if \(!a\.length\) await foundingBirth\.ensureBirth\(\);\s*return foundingMode\.foundingModeFor\(\.\.\.a\);/);
 });
 
 test('BOTH applyAccess callers pass it, or the index would never show the band', () => {

package/tests/genesis_home.mjs

@@ -91,6 +91,58 @@ test('a plan out of range is refused with the reason', () => {
   assert.equal(gh.parsePlan({ expected_builders: 0 }).reason, 'bad_expected_builders');
 });
 
+// ── the demo's expedited plan (task 1004506) ────────────────────────────────
+
+test('a demo\'s stages are minutes, fitted to a fifth of its time box (10 min to 2 h)', () => {
+  const sum = (m) => Object.values(m).reduce((a, b) => a + b, 0);
+  assert.deepEqual(gh.demoMinutes(4), { scope: 14, strategize: 10, charter: 10, legalize: 5, legislation: 10 },
+    '3 people × 4 hours: about 48 minutes of genesis, then building');
+  assert.deepEqual(Object.keys(gh.demoMinutes(1)), STAGES5);
+  for (const h of [1, 2, 4, 8, 20, 40]) {
+    const total = sum(gh.demoMinutes(h));
+    assert.ok(total <= h * 60 * 0.25, `${h}h: genesis (${total} min) leaves most of the time box for building`);
+    assert.ok(total >= 8 && total <= 125, `${h}h: ${total} min is inside the bounds`);
+    assert.ok(Object.values(gh.demoMinutes(h)).every((m) => Number.isInteger(m) && m >= 1));
+  }
+});
+
+test('the demo plan is the settled one: Monarchy / BDFL, one pass, no advisors, the demo\'s people', () => {
+  const r = gh.parsePlan(gh.demoPlan({ people: 3, hours_each: 4 }));
+  assert.equal(r.ok, true, JSON.stringify(r));
+  assert.equal(r.plan.government, 'monarchy');
+  assert.equal(r.plan.passes, 1);
+  assert.equal(r.plan.advisors, 'none');
+  assert.equal(r.plan.expected_builders, 3);
+  assert.equal(r.plan.existing, false);
+  assert.deepEqual(r.plan.demo, { people: 3, hours_each: 4 });
+  assert.deepEqual(r.plan.minutes, gh.demoMinutes(4));
+  assert.equal(gh.parsePlan({ demo: { people: 0, hours_each: 4 } }).reason, 'bad_demo');
+  assert.equal(gh.parsePlan({ minutes: { scope: 5 } }).reason, 'bad_minutes', 'every stage needs its minutes');
+  assert.equal(gh.parsePlan({}).plan.minutes, undefined, 'a real project\'s plan stays in days');
+});
+
+test('the plan route does not name the demo fields, so only the birth can write a demo plan', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'onboarding', 'routes', 'onboarding.js'), 'utf8');
+  const schema = src.slice(src.indexOf("router.post('/founding/plan'"), src.indexOf("router.post('/founding/stages"));
+  assert.ok(schema.includes('validateOrRespond'));
+  assert.doesNotMatch(schema, /\bdemo\b|\bminutes\b/);
+});
+
+test('a demo genesis reads in minutes: each stage due minutes after it began', () => {
+  const plan = gh.parsePlan(gh.demoPlan({ people: 2, hours_each: 4 })).plan;
+  const g = gh.shapeGenesis({
+    mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 },
+    plan, stageAt: { scope: '2026-10-01T09:00:00.000Z' },
+  });
+  assert.deepEqual(g.demo, { people: 2, hours_each: 4 });
+  assert.equal(g.stages[0].minutes, 14);
+  assert.equal(g.stages[0].due, '2026-10-01T09:14:00.000Z');
+  const real = gh.shapeGenesis({ mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 }, plan: gh.parsePlan({}).plan, stageAt: { scope: '2026-10-01T09:00:00.000Z' } });
+  assert.equal(real.demo, null);
+  assert.equal(real.stages[0].minutes, null);
+  assert.equal(real.stages[0].due, '2026-10-08T09:00:00.000Z', 'a real project is unchanged: days');
+});
+
 // ── the flow, end to end over fakes ──────────────────────────────────────────
 
 function world({ withGovernment = true } = {}) {
@@ -232,7 +284,7 @@ test('every genesis write is the project owner\'s; the read is any signed-in bui
 
 const CARD = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'genesis-home.js'), 'utf8');
 
-function bootCard({ founding }) {
+function bootCard({ founding, data = { genesis: null } }) {
   const calls = [];
   let widget = null;
   let observer = null;
@@ -240,7 +292,7 @@ function bootCard({ founding }) {
   const sandbox = {
     window: {
       OTB: { escapeHtml: (s) => String(s), contributeHallWidget: (w) => { widget = w; } },
-      BongosClient: { createClient: () => ({ request: async (m, p) => { calls.push(`${m} ${p}`); return { ok: true, status: 200, data: { genesis: null } }; } }) },
+      BongosClient: { createClient: () => ({ request: async (m, p) => { calls.push(`${m} ${p}`); return { ok: true, status: 200, data }; } }) },
     },
     document: { documentElement: { getAttribute: (k) => attrs[k] || null } },
     MutationObserver: class { constructor(fn) { observer = fn; } observe() {} disconnect() {} },
@@ -277,6 +329,23 @@ test('founding mode stamped after mount still starts the card, once', async () =
   assert.deepEqual(b.calls, ['GET /api/bongos/founding/genesis']);
 });
 
+test('a demo\'s genesis card: no decide form, the settled plan in one line, each stage in minutes (task 1004506)', async () => {
+  const genesis = gh.shapeGenesis({
+    mode: { stage: 'scope', stage_number: 1, stage_count: 5, day: 1 },
+    plan: gh.parsePlan(gh.demoPlan({ people: 3, hours_each: 4 })).plan,
+    stageAt: { scope: '2026-10-01T09:00:00.000Z' },
+  });
+  const { host } = bootCard({ founding: true, data: { genesis, viewer_id: '1' } });
+  await new Promise((r) => setImmediate(r));
+  await new Promise((r) => setImmediate(r));
+  assert.equal(host.hidden, false);
+  assert.match(host.innerHTML, /Monarchy \/ BDFL, 3 people, 4 hours each/);
+  assert.match(host.innerHTML, /about 49 minutes/);
+  assert.match(host.innerHTML, /14 min, due /, 'the stage in progress is due at a time, not a date');
+  assert.match(host.innerHTML, /Stage 1 of 5 · scope · demo/);
+  assert.doesNotMatch(host.innerHTML, /data-genesis-plan/, 'a demo never shows the decide form');
+});
+
 test('the hall carries the five life plates byte-identical to the world\'s', () => {
   const world = path.join(ROOT, 'modules', 'public-landing', 'public', 'assets', 'world');
   const hall = path.join(ROOT, 'modules', 'hall-ui', 'public', 'genesis');

package/tests/hub_map_orb_states.mjs

@@ -66,6 +66,10 @@ const PA_START = SCRIPT.indexOf('function planetAttrs(');
 const PA_END = SCRIPT.indexOf('var PLANET_SHAPE_WORDS');
 assert.ok(PA_START > 0 && PA_END > PA_START, 'planetAttrs must still be sliceable');
 const PLANET_ATTRS = SCRIPT.slice(PA_START, PA_END);
+// The row's site door (task 1004505) and the rule it asks, sliced the same way.
+const ADDRESS_READY = (SCRIPT.match(/function addressReady\(inst\) \{[^\n]*\}/) || [''])[0];
+const SITE_HREF = (SCRIPT.match(/function siteHref\(p\) \{[^\n]*\}/) || [''])[0];
+assert.ok(ADDRESS_READY && SITE_HREF, 'addressReady and siteHref must still be sliceable');
 
 // ── the DOM stub ─────────────────────────────────────────────────────────────
 // Narrow on purpose: it supports exactly what the region touches, so it stays
@@ -111,7 +115,7 @@ function boot() {
     listedDate: (iso) => String(iso),
   };
   vm.createContext(sandbox);
-  vm.runInContext(PLANET_ATTRS + '\n' + REGION, sandbox);
+  vm.runInContext(PLANET_ATTRS + '\n' + ADDRESS_READY + '\n' + SITE_HREF + '\n' + REGION, sandbox);
   return {
     sandbox,
     sky,