@bongos/core 1.20.83 → 1.21.2

package/modules/hall-ui/public/roster.html

@@ -34,6 +34,9 @@
              link into index.html. It is a page now; /#leaderboard redirects here. -->
         <section class="scroll" id="roster-scroll" aria-labelledby="roster-h">
           <h2 id="roster-h" class="scroll__h">The roster<span class="count-pill" id="roster-count" hidden></span></h2>
+          <!-- The role toggle (task 1004437, owner decision (b)): Everyone, then one
+               chip per craft; a craft ranks by the credits earned in it. -->
+          <div class="roster-roles" id="roster-roles" role="group" aria-label="Show"></div>
           <div id="roster-filters"></div>
           <div id="roster-body">
             <div class="profile__placeholder">Loading the roster…</div>

package/modules/hall-ui/public/roster.js

@@ -49,17 +49,31 @@
     'first-parallel-claim': '⚓',
     'streak-3': '\u{1F525}',
     'streak-7': '\u{1F30B}',
-    'art-pipeline-shipper': '\u{1F3A8}',
+    // task 1004438: renamed Art Pipeline Engineer; the palette is the artist's now
+    'art-pipeline-shipper': '\u{1F6E0}\u{FE0F}',
+    'first-thought-ignited': '\u{1F4A1}',
+    'first-full-idea': '\u{1F4DC}',
+    'first-board-ratification': '\u{1F3DB}\u{FE0F}',
+    'thought-built-ten': '\u{1F31F}',
+    'first-page-approved': '\u{1F3A8}',
+    'ten-pages-approved': '\u{1F5BC}\u{FE0F}',
+    'whole-surface-tweaked': '\u{1F5FA}\u{FE0F}',
     'gds-shipper': '⚙️',
     'breaking-the-100c-bar': '\u{1F4AF}',
   };
+  // An achievement id as a sentence: "first-page-approved" → "First page approved".
+  function achWords(id) {
+    var s = String(id || '').replace(/-/g, ' ');
+    return s.charAt(0).toUpperCase() + s.slice(1);
+  }
   function achRowHtml(ids) {
     if (!Array.isArray(ids) || !ids.length) return '';
     var inner = ids.map(function (id) {
       var emoji = ACH_EMOJI[id];
-      // Title is the achievement id (kebab) — terse enough that hover discloses
-      // the laurel without overstating the prose.
-      return emoji ? '<span class="lb-ach" title="' + esc(id) + '" aria-label="' + esc(id) + '">' + emoji + '</span>' : '';
+      // The title is the achievement's name as words ("First page approved"), not
+      // its id slug (task 1004438): it is what a hover shows and a screen reader says.
+      var words = achWords(id);
+      return emoji ? '<span class="lb-ach" title="' + esc(words) + '" aria-label="' + esc(words) + '">' + emoji + '</span>' : '';
     }).join('');
     return inner ? '<span class="lb-ach-row" aria-label="achievements">' + inner + '</span>' : '';
   }
@@ -94,9 +108,34 @@
     return '<span class="dir-who">' + avatar + '<span class="dir-who__t">' + nameHtml + login + '</span></span>';
   }
 
+  // task 1004437 (WA6.RP07): the roles. Each row's `roles` block is the public
+  // list's own (src/bongos/role-stats.js readRolesForBuilders): `shown` is the
+  // main role first, then every craft the builder has EARNED in — evidence of
+  // work, not only what they declared — and `credits_by_craft` is the ledger
+  // split. Owner decision (b): a column naming them AND the role toggle above,
+  // which ranks by the credits earned in that craft. The figure a role ranks by
+  // is in the row (ADR 0255: a public list is ordered only by what it publishes).
+  var CRAFTS = ['engineer', 'artist', 'ideator'];
+  var CRAFT_WORD = { engineer: 'Engineer', artist: 'Artist', ideator: 'Ideator' };
+  var ROLE_CHIPS = [['', 'Everyone'], ['engineer', 'Engineers'], ['artist', 'Artists'], ['ideator', 'Ideators']];
+  function shownOf(b) { return (b.roles && Array.isArray(b.roles.shown)) ? b.roles.shown : []; }
+  function craftCredits(b, craft) {
+    var by = b.roles && b.roles.credits_by_craft;
+    return by ? (Number(by[craft]) || 0) : 0;
+  }
+  function creditOf(b) { return role ? craftCredits(b, role) : (Number(b.total_credits) || 0); }
+  function rolesHtml(b) {
+    var shown = shownOf(b);
+    if (!shown.length) return '<span class="lb-roles lb-roles--none">—</span>';
+    return '<span class="lb-roles">' + shown.map(function (c, i) {
+      return '<span class="lb-role' + (i === 0 ? ' lb-role--lead' : '') + '">' + esc(CRAFT_WORD[c] || c) + '</span>';
+    }).join('') + '</span>';
+  }
+
   var all = [];
   var query = '';
   var sortBy = '';
+  var role = '';
 
   // PLACE IS CANONICAL, not the row's position in the current sort.
   // hall-render's leaderboardPlace() already defines a builder's place as
@@ -108,6 +147,16 @@
     rows.slice()
       .sort(function (a, b) { return (Number(b.total_credits) || 0) - (Number(a.total_credits) || 0); })
       .forEach(function (b, i) { b.__place = i + 1; });
+    // A role's place is the same idea inside that role: credits earned in the
+    // craft, descending, among the builders it is shown for. Stamped once too,
+    // so the place under a role toggle does not renumber under a search.
+    rows.forEach(function (b) { b.__placeBy = {}; });
+    CRAFTS.forEach(function (c) {
+      rows.filter(function (b) { return shownOf(b).indexOf(c) !== -1; })
+        .map(function (b, i) { return { b: b, i: i }; })
+        .sort(function (x, y) { return (craftCredits(y.b, c) - craftCredits(x.b, c)) || (x.i - y.i); })
+        .forEach(function (x, i) { x.b.__placeBy[c] = i + 1; });
+    });
     // The efficiency title is stamped here too, so the division and the string
     // work happen ONCE per load rather than per visible row per render (every
     // sort, search keystroke and page turn re-renders).
@@ -116,6 +165,7 @@
   }
 
   function matches(b) {
+    if (role && shownOf(b).indexOf(role) === -1) return false;
     if (!query) return true;
     var hay = ((b.github_login || '') + ' ' + (b.display_name || '')).toLowerCase();
     return hay.indexOf(query) !== -1;
@@ -130,7 +180,8 @@
     tokens: function (b) { return -(Number(b.tokens_used) || 0); },
   };
   function ordered(rows) {
-    var key = SORTS[sortBy];
+    // The default lens is credits; under a role it is the credits that role earned.
+    var key = SORTS[sortBy] || (role ? function (b) { return -craftCredits(b, role); } : null);
     if (!key) return rows;
     return rows.map(function (b, i) { return { b: b, i: i }; })
       .sort(function (x, y) { return (key(x.b) - key(y.b)) || (x.i - y.i); })
@@ -140,7 +191,14 @@
   var pager = kit.makePager('roster', 'hall-roster-per-page', { defaultPerPage: 25 });
   var ledger = null;
 
+  // Tokens only mean something for AI sessions. A builder who works in the
+  // browser (an artist in the studio, an ideator in the room) records none, and
+  // a 0 beside them reads as "did nothing" (task 1004437): their cell says so in
+  // words instead, and the tokens-per-credit figure is offered only where there
+  // are tokens to divide.
+  function hasTokens(b) { return (Number(b.tokens_used) || 0) > 0; }
   function efficiencyTitle(b) {
+    if (!hasTokens(b)) return 'No AI sessions recorded — this builder’s work is not measured in tokens';
     var credits = Number(b.total_credits) || 0;
     var one = currencyLabel().toLowerCase().replace(/s$/, '');
     if (credits <= 0) return 'no ' + currencyLabel().toLowerCase() + ' earned yet';
@@ -168,20 +226,69 @@
   }
 
   function rowHtml(b) {
+    var place = role ? (b.__placeBy && b.__placeBy[role]) : b.__place;
+    var tokens = hasTokens(b)
+      ? esc(fmtInt(b.tokens_used))
+      : '<span class="lb-none" aria-label="No AI sessions">—</span>';
     return '<tr>'
-      + '<td class="ledger__num ledger__place">' + esc(String(b.__place || '—')) + idHtml(b) + '</td>'
+      + '<td class="ledger__num ledger__place">' + esc(String(place || '—')) + idHtml(b) + '</td>'
       + '<td>' + whoHtml(b) + foundingHtml(b) + achRowHtml(b.achievements) + '</td>'
+      + '<td class="ledger__roles">' + rolesHtml(b) + '</td>'
       + '<td class="ledger__rank">' + rankBadgeHtml(b.rank) + '</td>'
-      + '<td class="ledger__num">' + esc(fmtInt(b.total_credits)) + '</td>'
+      + '<td class="ledger__num">' + esc(fmtInt(creditOf(b))) + '</td>'
       + '<td class="ledger__num">' + esc(fmtInt(b.karma)) + '</td>'
-      + '<td class="ledger__num" title="' + esc(b.__eff || '') + '">' + esc(fmtInt(b.tokens_used)) + '</td>'
+      + '<td class="ledger__num" title="' + esc(b.__eff || '') + '">' + tokens + '</td>'
       + '</tr>';
   }
 
+  function columns() {
+    return ['Place', 'Builder', 'Roles', 'Rank',
+      { label: role ? currencyLabel() + ' as ' + CRAFT_WORD[role].toLowerCase() : currencyLabel(), class: 'ledger__num' },
+      { label: 'Karma', class: 'ledger__num' },
+      { label: 'Tokens', class: 'ledger__num' }];
+  }
+
+  function makeRosterLedger() {
+    body.textContent = '';
+    body.className = '';
+    ledger = kit.makeLedger({
+      mount: body,
+      columns: columns(),
+      rowHtml: rowHtml,
+      emptyMsg: role
+        ? 'No builder on the roster has earned as ' + CRAFT_WORD[role].toLowerCase() + ' yet, or none matches that search.'
+        : 'No builder on the roster matches that search.',
+      pager: pager,
+    });
+  }
+
   function rerender() {
     if (ledger) ledger.render(ordered(all.filter(matches)));
   }
 
+  // The role toggle (owner decision (b)): Everyone, then one per craft. A pressed
+  // chip ranks by the credits that craft earned and shows only the builders it
+  // is shown for. The ledger is rebuilt so the credits header names the craft.
+  function roleChipsHtml() {
+    return ROLE_CHIPS.map(function (c) {
+      return '<button type="button" class="roster-role" data-role="' + esc(c[0]) + '" aria-pressed="' + (c[0] === role) + '">' + esc(c[1]) + '</button>';
+    }).join('');
+  }
+  function mountRoleChips() {
+    var mount = document.getElementById('roster-roles');
+    if (!mount) return;
+    mount.innerHTML = roleChipsHtml();
+    mount.addEventListener('click', function (e) {
+      var btn = e.target.closest('[data-role]');
+      if (!btn || btn.dataset.role === role) return;
+      role = btn.dataset.role;
+      mount.querySelectorAll('[data-role]').forEach(function (b) { b.setAttribute('aria-pressed', String(b.dataset.role === role)); });
+      pager.page = 1;
+      makeRosterLedger();
+      rerender();
+    });
+  }
+
   function notice(msg) {
     body.innerHTML = '';
     body.className = 'note';
@@ -221,23 +328,16 @@
         rerender();
       },
     });
-    body.textContent = '';
-    body.className = '';
-    ledger = kit.makeLedger({
-      mount: body,
-      columns: ['Place', 'Builder', 'Rank',
-        { label: currencyLabel(), class: 'ledger__num' },
-        { label: 'Karma', class: 'ledger__num' },
-        { label: 'Tokens', class: 'ledger__num' }],
-      rowHtml: rowHtml,
-      emptyMsg: 'No builder on the roster matches that search.',
-      pager: pager,
-    });
+    mountRoleChips();
+    makeRosterLedger();
     rerender();
   }
 
   var foundingLoad = window.OTBFounding ? window.OTBFounding.load() : Promise.resolve([]);
-  fetch('/api/bongos/leaderboard', { headers: { Accept: 'application/json' } })
+  // The PUBLIC list (task 1004437): the same rows the authed /leaderboard
+  // carries plus each builder's roles, and the one the status page reads, so
+  // the hall and the public page cannot rank a role differently.
+  fetch('/api/bongos/public/leaderboard', { headers: { Accept: 'application/json' } })
     .then(function (r) {
       if (!r.ok) throw new Error('http ' + r.status);
       return r.json();

package/modules/hall-ui/public/roster.states.json

@@ -1,5 +1,5 @@
 {
-  "_": "Builders — this project's OWN roster, ranked by credits earned (task 1003441, goal 1000075). Was the #leaderboard hash view on index.html; /#leaderboard now redirects here. Deliberately UNGATED, because its one data source (GET /leaderboard) is deliberately unauthenticated and mirrors the public status surface — so unlike a gated page's states file the `out` state below renders the real page rather than a seal. Populated look: the hall-preview harness (scripts/hall-preview/fixtures/leaderboard.json carries thirteen builders with avatars, ranks, karma and tokens).",
+  "_": "Builders — this project's OWN roster, ranked by credits earned (task 1003441, goal 1000075). Was the #leaderboard hash view on index.html; /#leaderboard now redirects here. Deliberately UNGATED, because its one data source (GET /leaderboard) is deliberately unauthenticated and mirrors the public status surface — so unlike a gated page's states file the `out` state below renders the real page rather than a seal. Populated look: the hall-preview harness (scripts/hall-preview/fixtures/public__leaderboard.json, since task 1004437 the list the page reads: fifteen builders with avatars, ranks, karma, tokens and each one's roles, including an artist and an ideator with no AI sessions).",
   "page": "/builders/roster",
   "surface": "hall-ui",
   "stub": {
@@ -44,6 +44,31 @@
         ]
       }
     },
+    "artists": {
+      "_": "The role toggle with Artists pressed (task 1004437, owner decision (b)): only the builders shown as artists, ranked by the credits that craft earned, the credits header naming the craft. Against the harness the browser-only artist (2001) leads, with a dash where an AI builder's tokens would be. The harness serves public__leaderboard.json, which carries the roles.",
+      "auth": true,
+      "actions": [
+        [
+          "wait",
+          700
+        ],
+        [
+          "click",
+          "[data-role=\"artist\"]"
+        ],
+        [
+          "wait",
+          200
+        ]
+      ],
+      "expect": {
+        "visible": [
+          "#roster-scroll",
+          "#roster-roles",
+          ".lb-roles"
+        ]
+      }
+    },
     "search": {
       "auth": true,
       "actions": [

package/modules/hall-ui/records/builders-roster.md

@@ -8,3 +8,23 @@
 - **It is deliberately UNGATED,** and `tests/hall_page_gate_map.mjs` spells that out rather than defaulting. Its one data source, `GET /leaderboard`, is deliberately unauthenticated and mirrors the public status surface; a page must not be gated tighter than the API it fronts, and it was already reachable to a stranger as a view on the ungated index. No visibility predicate is applied and that is correct — privacy suppresses cross-project surfaces only, so a `private` builder still appears on the roster of a project they build on (ADR 0225).
 
 Pinned by `tests/hall_nav.mjs` (the Community group's middle id is `roster`) and `tests/hall_page_gate_map.mjs`. Measured through `roster.states.json` — whose `out` state renders the REAL page, since the page is ungated.
+
+## The roles (task 1004437, WA6.RP07)
+
+Owner decision (b), 2026-09-30: the leaderboard gets BOTH a column naming each builder's roles and the Everyone / Engineers / Artists / Ideators toggle above it. The approved mock is `docs/design/mocks/profile-roles/` (`?state=board`, `?state=board-artists`).
+
+- **The roster now reads `GET /public/leaderboard`,** the list the status page reads, which carries each row's `roles` (`src/bongos/role-stats.js` `readRolesForBuilders`: the profile's own main/shown rules, two reads for the whole page) and, since this task, `karma`. The hall and the public page cannot rank a role differently. The authed `/leaderboard` is unchanged and no longer read by the hall.
+- **Roles column:** one pill per role in `roles.shown`, the main one a step stronger. `shown` is the main role plus every craft the builder has EARNED in, so it is evidence of work, not only a declared preference.
+- **The toggle** keeps the builders a craft is shown for and ranks them by the credits that craft earned (`roles.credits_by_craft`, in the row: ADR 0255). The place column becomes the place inside that craft, the credits header says "Credits as artist", and the karma/rank/tokens lenses still apply on top.
+- **Tokens only where they apply.** A builder with no recorded AI session (an artist in the studio, an ideator in the room) reads a dash, and the cell's tooltip says no AI sessions were recorded, instead of a 0 and a "0 tokens per credit" figure that read as "did nothing".
+- **Home's Standing card** reads the same list and adds "#N as an artist" beside "#N on the leaderboard" when the place inside the builder's main role differs from the overall one (`hall-render.js` `rolePlaceText`).
+- **The status page** names each builder's roles under their name, on that page's own palette (`status.js` `renderRoles`).
+
+Pinned by `tests/leaderboard_roles.mjs` (the read, the route, the REAL roster.js over the harness fixture with the toggle clicked, the Standing card's place and the status renderer, run). The `artists` state in `roster.states.json` renders the toggle pressed.
+
+### Deliberate differences from the mock (RP07)
+
+- **No "Best known for" column.** Each row's headline count (works shipped, pages approved, thoughts ignited) is a per-builder read in three different modules; the list would pay three more reads for every page of builders. The profile, one click away, leads with exactly that number.
+- **The roster keeps its live columns**: place with the builder's number, rank, karma and tokens, the founding mark and the laurels, and its search and sort lenses. The mock draws the leaderboard bare; the live hall's chrome wins (the blend rule).
+- **The column is "Roles", not "Preferred roles"**: it lists roles the builder has earned in as well as the one they chose, so "preferred" would understate it.
+- **The status page has the roles but not the toggle.** It is a one-glance public dashboard of the top builders on its own palette; the toggle lives on the roster, which is the leaderboard a builder works from.

package/modules/lifecycle/publish-reconciler.js

@@ -944,6 +944,29 @@ async function runPromotionSweep(deps = {}) {
   }
 }
 
+// The craft-achievement backfill (task 1004438, WA6.RP08): the one badge a
+// migration cannot backfill, "A Whole Surface", needs the page inventory, which is
+// a file the database never sees. Run ONCE per process start, on the first tick,
+// through the reward port (economy is optional; no port, no sweep). Pure DB and
+// idempotent, so a restart that runs it again unlocks nothing twice; a failure is
+// logged and never touches the other sweeps.
+let craftBackfillDone = false;
+async function runCraftAchievementBackfill(deps = {}) {
+  const { logFn, errFn } = loggers(deps);
+  if (craftBackfillDone && !deps.forceCraftBackfill) return { skipped: 'already_ran' };
+  craftBackfillDone = true;
+  const reward = deps.reward || seams.resolveOptional('reward');
+  if (!reward || typeof reward.backfillCraftAchievements !== 'function') return { skipped: 'unsupported' };
+  try {
+    const out = await reward.backfillCraftAchievements({});
+    if (out && out.unlocked) logFn(`[publish-reconciler] craft achievements: ${out.unlocked} unlocked across ${out.checked} builder(s)`);
+    return out;
+  } catch (e) {
+    errFn(`[publish-reconciler] craft achievement backfill (non-blocking): ${e && e.message}`);
+    return { skipped: 'error', error: e && e.message };
+  }
+}
+
 // Start the periodic sweep. Idempotent (a second call is a no-op). Kill-switched
 // by PUBLISH_RECONCILER_DISABLED=1 (purely additive bookkeeping, so it's ON by
 // default whenever a push credential is configured; the route's getPublishStatus
@@ -964,6 +987,7 @@ function start(deps = {}) {
     runCostSweep(deps).catch(crashHandler('cost sweep'));
     runCriterionSweep(deps).catch(crashHandler('criterion sweep'));
     runPromotionSweep(deps).catch(crashHandler('promotion sweep'));
+    runCraftAchievementBackfill(deps).catch(crashHandler('craft achievement backfill'));
   };
 
   firstTimer = setTimeout(tick, FIRST_SWEEP_DELAY_MS);
@@ -1002,6 +1026,7 @@ module.exports = {
   runCostSweep,
   runPromotionSweep,
   runCriterionSweep,
+  runCraftAchievementBackfill,
   couldBeStaleGenerated,
   describeTarget,
   INTERVAL_MS,

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 };