@bongos/core 1.20.47 → 1.20.48

package/modules/onboarding/founding-mode.js

@@ -0,0 +1,185 @@
+'use strict';
+
+// modules/onboarding/founding-mode.js — PROJECT FOUNDING MODE: is this project still
+// being founded, and which stage of genesis is it on? (task 1004422 / BV2.PS03, goal
+// 1000121; design of record docs/design/project-startup-direction.md.)
+//
+// THE BLEND RULE THIS FILE SERVES (owner, 2026-09-30). Genesis is a MODE the existing
+// builders hall wears, never a second hall. So this file answers ONE question for the
+// hall shell — founding or not, and at which stage — and the shell stamps the answer on
+// the document the way it stamps social mode (`html[data-social]`). Nothing here renders
+// anything, and a project that is not founding gets `null`, which the shell reads as OFF:
+// the hall then renders exactly as it does today.
+//
+// WHY THE ONBOARDING MODULE. Founding is the FOUNDER-side counterpart of the joiner
+// state machine this module already owns (onboarding-state.js graduates a newcomer; this
+// graduates a project). It lives in project_settings (migration core_231) through the
+// doorway's one accessor, like mingle.enabled, rather than a table of its own — one row
+// per project is the whole state, and "do not fork a second settings store" is that
+// accessor's own rule.
+//
+// FAIL POSTURE: CLOSED, i.e. OFF. An unreadable, absent, or malformed state is NOT
+// founding. The failure this guards against is the owner's no-hijack condition: a hall
+// wrongly stuck in founding mode would dim rooms that are really open. A hall wrongly
+// NOT in founding mode only loses a banner. So every doubtful read answers null.
+
+// The genesis stages, in order. 'decide' is the pre-stage the founder plans in; the
+// five after it are the stages proper (spec C4). The order IS the data: a room wakes
+// when the stage that wakes it has been left behind.
+const STAGES = Object.freeze(['decide', 'scope', 'strategize', 'charter', 'legalize', 'legislation']);
+
+// Which hall rooms each finished stage wakes (the direction doc's "How rooms wake"
+// table). Keyed by the shell's NAV item ids, so the client applies it without a second
+// mapping of its own — a surface that re-derived this could disagree with the server.
+// 'community' wakes only when the planet is ALIVE, which is when founding mode switches
+// off entirely, so during founding it is always asleep.
+const WAKES = Object.freeze({
+  scope: Object.freeze(['roadmap', 'goals', 'goal-map']),
+  strategize: Object.freeze(['work']),
+  charter: Object.freeze(['board-room']),
+  legalize: Object.freeze(['economy']),
+  legislation: Object.freeze(['ranks']),
+});
+const WAKES_WHEN_ALIVE = Object.freeze(['collab', 'roster']);
+
+// The project_settings keys. Namespaced 'founding.' like 'mingle.' and 'attention.'.
+const KEYS = Object.freeze({
+  ACTIVE: 'founding.active',
+  STAGE: 'founding.stage',
+  STARTED_AT: 'founding.started_at',
+});
+
+// The only 'on' spelling accepted, mirroring mingle's consent-gate parse: an explicit,
+// recognised yes. Anything else is off.
+function parseActive(raw) {
+  if (raw == null) return false;
+  return ['true', '1', 'on', 'yes'].includes(String(raw).trim().toLowerCase());
+}
+
+// asleepRooms(stage) — PURE. For a known stage, { navId: wakingStage } for every room
+// still asleep. A room is awake once its waking stage is BEHIND the current one.
+function asleepRooms(stage) {
+  const at = STAGES.indexOf(stage);
+  if (at < 0) return null;
+  const asleep = {};
+  for (const [wakingStage, ids] of Object.entries(WAKES)) {
+    if (STAGES.indexOf(wakingStage) >= at) for (const id of ids) asleep[id] = wakingStage;
+  }
+  for (const id of WAKES_WHEN_ALIVE) asleep[id] = 'alive';
+  return asleep;
+}
+
+// dayOf(startedAt, now) — PURE. Day 1 is the founding day. null when unreadable, so a
+// bad timestamp drops the day from the band rather than printing "day NaN".
+function dayOf(startedAt, now = new Date()) {
+  if (!startedAt) return null;
+  const t = new Date(startedAt).getTime();
+  if (!Number.isFinite(t)) return null;
+  const days = Math.floor((now.getTime() - t) / 86400000) + 1;
+  return days >= 1 ? days : 1;
+}
+
+// shapeFoundingMode(rows, now) — PURE. rows = { active, stage, startedAt } raw strings
+// (or nulls). Returns the /me payload, or null for "not founding" in any form.
+function shapeFoundingMode(rows, now = new Date()) {
+  if (!rows || !parseActive(rows.active)) return null;
+  const stage = rows.stage == null ? 'decide' : String(rows.stage).trim().toLowerCase();
+  const asleep = asleepRooms(stage);
+  if (!asleep) return null; // an unknown stage is not a stage — fail closed (OFF)
+  const index = STAGES.indexOf(stage);
+  return {
+    active: true,
+    stage,
+    // 0 while deciding, then 1..5 through the stages proper.
+    stage_number: index,
+    stage_count: STAGES.length - 1,
+    day: dayOf(rows.startedAt, now),
+    asleep,
+    // Who closing the current stage is waiting on (spec D7) — display names, at most
+    // five, from the government module's genesis-stage sitting (task 1004429). null
+    // when the stage is not sitting, nobody is left to vote, or the read is missing.
+    waiting_on: Array.isArray(rows.waitingOn) && rows.waitingOn.length
+      ? rows.waitingOn.slice(0, 5).map((n) => String(n))
+      : null,
+  };
+}
+
+// foundingModeFor(deps) — the /me read. Resolves the three rows through the doorway's
+// project-settings accessor (injectable for tests). Never throws: any read failure is
+// "not founding".
+// Three primary-key reads in parallel: the doorway's project-settings accessor is
+// single-key by design (one accessor, one table), and a founding project is a short
+// window of a project's life, so a batched read is not worth a second accessor.
+async function foundingModeFor(deps = {}) {
+  const get = deps.getSetting || require('../../src/module-api').projectSettings.get;
+  let shaped;
+  try {
+    const [active, stage, startedAt] = await Promise.all([
+      get(KEYS.ACTIVE), get(KEYS.STAGE), get(KEYS.STARTED_AT),
+    ]);
+    shaped = shapeFoundingMode({
+      active: active && active.value,
+      stage: stage && stage.value,
+      startedAt: startedAt && startedAt.value,
+    }, deps.now || new Date());
+  } catch (_) {
+    return null;
+  }
+  if (!shaped) return null;
+  // The waiting-on names come from the government module's genesis-stage read
+  // (genesisStageStatus on its port, task 1004429: one entry per stage, each with
+  // a state and, while sitting, the members still to vote under the item's own
+  // snapshot). Optional and fail-open: a missing port or a failed read leaves the
+  // band without the names, never without the mode.
+  try {
+    const waitingOnFor = deps.waitingOnFor || waitingOnFromGovernment(
+      deps.government !== undefined ? deps.government : require('../../src/module-api').resolveOptional('government'),
+    );
+    if (waitingOnFor) {
+      const names = await waitingOnFor(shaped.stage);
+      if (Array.isArray(names) && names.length) shaped.waiting_on = names.slice(0, 5).map((n) => String(n));
+    }
+  } catch (_) { /* fail open: the band shows the stage without the names */ }
+  return shaped;
+}
+
+// waitingOnFromGovernment(gov) — a stage -> [display name] reader over the government
+// port's genesisStageStatus(), or null when the port does not offer it. Only a stage
+// that is SITTING waits on anyone; not_put, passed and returned wait on nobody.
+function waitingOnFromGovernment(gov) {
+  if (!gov || typeof gov.genesisStageStatus !== 'function') return null;
+  return async (stage) => {
+    const status = await gov.genesisStageStatus();
+    const row = status && Array.isArray(status.stages) ? status.stages.find((s) => s.key === stage) : null;
+    if (!row || row.state !== 'sitting' || !Array.isArray(row.waiting_on)) return [];
+    return row.waiting_on.map((m) => m.display_name || m.github_login).filter(Boolean);
+  };
+}
+
+// setFoundingMode({ active, stage }, builderId, deps) — the write the genesis home
+// (task 1004423) drives: start founding on a new project, move the stage, and switch
+// founding off when the planet comes alive. Refuses an unknown stage rather than storing
+// a value the read would then treat as OFF. Starting stamps started_at once.
+async function setFoundingMode({ active, stage } = {}, builderId = null, deps = {}) {
+  const settings = require('../../src/module-api').projectSettings;
+  const get = deps.getSetting || settings.get;
+  const set = deps.setSetting || settings.set;
+  if (stage != null && !STAGES.includes(stage)) {
+    const err = new Error(`unknown founding stage '${stage}'`);
+    err.code = 'bad_founding_stage';
+    throw err;
+  }
+  if (active === true) {
+    const started = await get(KEYS.STARTED_AT);
+    if (!started || !started.value) await set(KEYS.STARTED_AT, (deps.now || new Date()).toISOString(), builderId);
+  }
+  if (typeof active === 'boolean') await set(KEYS.ACTIVE, active ? 'true' : 'false', builderId);
+  if (stage != null) await set(KEYS.STAGE, stage, builderId);
+  return foundingModeFor({ getSetting: get, now: deps.now });
+}
+
+module.exports = {
+  STAGES, WAKES, WAKES_WHEN_ALIVE, KEYS,
+  parseActive, asleepRooms, dayOf, shapeFoundingMode, waitingOnFromGovernment,
+  foundingModeFor, setFoundingMode,
+};

package/modules/onboarding/port.js

@@ -40,6 +40,7 @@
 
 const onboardingState = require('./onboarding-state');
 const newcomerRestock = require('./newcomer-restock');
+const foundingMode = require('./founding-mode');
 
 module.exports = {
   // --- the newcomer onboarding state machine (onboarding-state.js) ---------
@@ -53,6 +54,12 @@ module.exports = {
   markStage: (...a) => onboardingState.markStage(...a),
   broadcastGraduation: (...a) => onboardingState.broadcastGraduation(...a),
 
+  // --- 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),
+  setFoundingMode: (...a) => foundingMode.setFoundingMode(...a),
+
   // --- the evergreen newcomer-chore restock (newcomer-restock.js) ----------
   // restock the just-claimed chore's shelf (claims.js / tasks.js); the Archon
   // backstop tops every chore up (tasks.js). SOURCE_TAG is the marker the claim

package/modules/ui-design/kit/fixtures/me-founding.json

@@ -0,0 +1,24 @@
+{
+  "builder": {
+    "id": "1",
+    "github_login": "builder",
+    "display_name": "A Builder",
+    "avatar_url": "/__kit/avatar.svg",
+    "rank": "archon"
+  },
+  "founding_mode": {
+    "active": true,
+    "stage": "strategize",
+    "stage_number": 2,
+    "stage_count": 5,
+    "day": 9,
+    "asleep": {
+      "work": "strategize",
+      "board-room": "charter",
+      "economy": "legalize",
+      "ranks": "legislation",
+      "collab": "alive",
+      "roster": "alive"
+    }
+  }
+}

package/modules/ui-design/kit/serve.js

@@ -277,7 +277,9 @@ function fileUnder(base, rel) {
 // is absolutised to this origin per request.
 const AVATAR_SVG = '<svg xmlns="http://www.w3.org/2000/svg" width="64" height="64" viewBox="0 0 64 64"><circle cx="32" cy="32" r="32" fill="#888"/><circle cx="32" cy="26" r="11" fill="#ddd"/><path d="M12 56c3-12 11-17 20-17s17 5 20 17" fill="#ddd"/></svg>';
 function me(origin) {
-  const m = JSON.parse(fs.readFileSync(path.join(FIXTURES, 'me.json'), 'utf8'));
+  // stub.fixtures may re-point the identity too (task 1004422: the founding-mode render) —
+  // the same ALIAS every other fixture honours, so a variant states file needs no stub code.
+  const m = JSON.parse(fs.readFileSync(path.join(FIXTURES, (ALIAS.me || 'me') + '.json'), 'utf8'));
   if (m.builder && typeof m.builder.avatar_url === 'string' && m.builder.avatar_url.startsWith('/')) m.builder.avatar_url = origin + m.builder.avatar_url;
   return m;
 }

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.47",
+  "version": "1.20.48",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.47",
+      "version": "1.20.48",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.47",
+  "version": "1.20.48",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8395,5 +8395,11 @@
       "id": "1003141",
       "text": "The Goals page now has the same bulk actions as the Tasks board: claim several tasks, release your own, or copy a prompt to work them in parallel or in order. Both pages now share one toolbar, so they stay in step."
     }
+  ],
+  "1.20.48": [
+    {
+      "id": "1004422",
+      "text": "While a new project is being founded, its builders hall now shows a clear \"project founding mode\" band at the top and dims the rooms that open later. A hall that isn't being founded stays exactly as it was."
+    }
   ]
 }

package/src/bongos/routes/me.js

@@ -187,7 +187,7 @@ module.exports = function buildMeRouter() {
       recentGrades, builderAvg, onboardingRow, shipCount, recentKarma, karma30d, discordLink, cliAuthed,
       behaviorPrefs, geminiKeyRow, needsRebaseTasks, foundingBuilder, helpRequestCount,
       taskRecommendationCount, boardVotesPending, socialMode, mingleIntroductionCount,
-      navPermissions,
+      navPermissions, foundingMode,
     ] = await Promise.all([
       db.getBuilderById(req.builder.id),
       lc().getActiveClaimsForBuilder(req.builder.id),
@@ -308,6 +308,16 @@ module.exports = function buildMeRouter() {
       // Same fan-out slot as the reads above, but it fails CLOSED rather than
       // open — null hides the link. See navPermissionsFor.
       navPermissionsFor(req.builder.id),
+      // task 1004422 (BV2.PS03): PROJECT FOUNDING MODE — is this project still being
+      // founded, and at which genesis stage. Same fan-out slot and posture as social
+      // mode: null (not founding, or unreadable) is OFF, and the hall then renders
+      // exactly as it does today, which is the owner's no-hijack condition.
+      (async () => {
+        try {
+          if (!onboarding || !onboarding.foundingModeFor) return null;
+          return await onboarding.foundingModeFor();
+        } catch (_) { return null; }
+      })(),
     ]);
     // V3.R84 (#302), criterion C3: the builder's month-to-date spend vs their
     // monthly budget. Surfaced here so the CLI (session-start ping) and the hall
@@ -378,6 +388,13 @@ module.exports = function buildMeRouter() {
       // when lifecycle is disabled or the read failed, and the shell treats null
       // as OFF — a mode that cannot be read is not on.
       social: socialMode,
+      // task 1004422 (BV2.PS03, goal 1000121): PROJECT FOUNDING MODE. Genesis is a
+      // mode the EXISTING hall wears (the blend rule, docs/design/project-startup-
+      // direction.md), so it rides /me exactly like social: the shell stamps
+      // html[data-founding], draws the founding band and dims the rooms still asleep.
+      // Shape: { active, stage, stage_number, stage_count, day, asleep: {navId: stage} },
+      // or null — and null is OFF, the hall as today.
+      founding_mode: foundingMode,
       // task 1003744: { '<atom>': boolean } for each permission key a hall nav
       // item may gate on (NAV_PERMISSION_ATOMS above), so an item can declare the
       // SAME atom its page is gated on instead of borrowing the nearest rank

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.47'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.48'; // 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_mode.mjs

@@ -0,0 +1,294 @@
+// tests/founding_mode.mjs — PROJECT FOUNDING MODE is a mode the existing hall wears,
+// never a second hall (task 1004422 / BV2.PS03, goal 1000121; the blend rule in
+// docs/design/project-startup-direction.md).
+//
+// The owner's no-hijack condition is the headline: a hall that is NOT founding must be
+// the hall it was. So the client half is RUN, not grepped. The real applyFounding is
+// sliced out of shell.js and driven over a small fake DOM, fed by the REAL server
+// shaper, so the path from the stored stage to the dimmed nav item is exercised
+// whole. Then OFF is proven to leave, and to restore, the DOM exactly.
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8').replace(/\r\n/g, '\n');
+const fm = require(path.join(ROOT, 'modules', 'onboarding', 'founding-mode.js'));
+
+const SHELL = read('modules', 'hall-ui', 'public', 'shell.js');
+const HALL_RENDER = read('modules', 'hall-ui', 'public', 'hall-render.js');
+const ME = read('src', 'bongos', 'routes', 'me.js');
+const PORT = read('modules', 'onboarding', 'port.js');
+
+// ── the server shaper (pure) ────────────────────────────────────────────────
+
+test('not founding in any form is null (OFF)', () => {
+  assert.equal(fm.shapeFoundingMode(null), null);
+  assert.equal(fm.shapeFoundingMode({ active: null }), null);
+  assert.equal(fm.shapeFoundingMode({ active: 'false', stage: 'scope' }), null);
+  assert.equal(fm.shapeFoundingMode({ active: 'maybe', stage: 'scope' }), null);
+});
+
+test('an unknown stage fails CLOSED — OFF, never a hall stuck half-asleep', () => {
+  assert.equal(fm.shapeFoundingMode({ active: 'true', stage: 'launch' }), null);
+});
+
+test('active with no stage yet is the decide pre-stage, and every room sleeps', () => {
+  const f = fm.shapeFoundingMode({ active: 'true' });
+  assert.equal(f.stage, 'decide');
+  assert.equal(f.stage_number, 0);
+  assert.equal(f.stage_count, 5);
+  for (const id of ['roadmap', 'goals', 'goal-map', 'work', 'board-room', 'economy', 'ranks', 'collab', 'roster']) {
+    assert.ok(id in f.asleep, `${id} sleeps while deciding`);
+  }
+});
+
+test('a room wakes once the stage that wakes it is behind', () => {
+  const f = fm.shapeFoundingMode({ active: 'true', stage: 'charter' });
+  for (const id of ['roadmap', 'goals', 'goal-map', 'work']) assert.ok(!(id in f.asleep), `${id} woke`);
+  assert.equal(f.asleep['board-room'], 'charter');
+  assert.equal(f.asleep.economy, 'legalize');
+  assert.equal(f.asleep.ranks, 'legislation');
+  assert.equal(f.asleep.collab, 'alive', 'community wakes only when the planet is alive');
+});
+
+test('the day counts from the founding day; an unreadable timestamp drops it', () => {
+  const now = new Date('2026-10-09T12:00:00Z');
+  assert.equal(fm.dayOf('2026-10-01T09:00:00Z', now), 9);
+  assert.equal(fm.dayOf('not a date', now), null);
+  assert.equal(fm.dayOf(null, now), null);
+});
+
+test('foundingModeFor fails closed when the settings read throws', async () => {
+  const got = await fm.foundingModeFor({ getSetting: async () => { throw new Error('db down'); } });
+  assert.equal(got, null);
+});
+
+test('setFoundingMode refuses an unknown stage and stamps started_at once', async () => {
+  const store = new Map();
+  const deps = {
+    getSetting: async (k) => (store.has(k) ? { key: k, value: store.get(k) } : null),
+    setSetting: async (k, v) => { store.set(k, String(v)); return { key: k, value: String(v) }; },
+    now: new Date('2026-10-01T00:00:00Z'),
+  };
+  await assert.rejects(fm.setFoundingMode({ stage: 'launch' }, 1, deps), /unknown founding stage/);
+  const first = await fm.setFoundingMode({ active: true, stage: 'decide' }, 1, deps);
+  assert.equal(first.stage, 'decide');
+  const stamp = store.get(fm.KEYS.STARTED_AT);
+  deps.now = new Date('2026-10-05T00:00:00Z');
+  await fm.setFoundingMode({ active: true, stage: 'scope' }, 1, deps);
+  assert.equal(store.get(fm.KEYS.STARTED_AT), stamp, 'started_at is not re-stamped');
+  assert.equal(await fm.setFoundingMode({ active: false }, 1, deps), null, 'switching off reads back as OFF');
+});
+
+test('every room the server can put to sleep is a real NAV item', () => {
+  // The map is keyed by NAV id so the client never re-derives it; a renamed NAV id
+  // would silently leave a room awake. Hold the two together.
+  const nav = SHELL.slice(SHELL.indexOf('var NAV = ['), SHELL.indexOf('var NAV_COLLAPSE_KEY'));
+  const ids = new Set([...nav.matchAll(/id: '([a-z-]+)'/g)].map((m) => m[1]));
+  const all = [...Object.values(fm.WAKES).flat(), ...fm.WAKES_WHEN_ALIVE];
+  for (const id of all) assert.ok(ids.has(id), `NAV has no item '${id}'`);
+});
+
+// ── the client, RUN over a fake DOM ─────────────────────────────────────────
+
+class El {
+  constructor(tag) {
+    this.tag = tag; this.id = ''; this.className = ''; this.dataset = {}; this.attrs = {};
+    this.children = []; this.parent = null; this.textContent = ''; this.innerHTML = '';
+    const self = this;
+    this.classList = {
+      add(c) { const s = new Set(self.className.split(' ').filter(Boolean)); s.add(c); self.className = [...s].join(' '); },
+      remove(c) { self.className = self.className.split(' ').filter((x) => x && x !== c).join(' '); },
+      contains(c) { return self.className.split(' ').includes(c); },
+    };
+  }
+  appendChild(c) { c.parent = this; this.children.push(c); return c; }
+  insertBefore(c, ref) { c.parent = this; const i = this.children.indexOf(ref); this.children.splice(i < 0 ? 0 : i, 0, c); return c; }
+  get parentNode() { return this.parent; }
+  removeChild(c) { this.children = this.children.filter((x) => x !== c); c.parent = null; return c; }
+  setAttribute(k, v) { this.attrs[k] = v; }
+  querySelector(sel) { return sel === '[data-wakes-tag]' ? (this.children.find((c) => 'data-wakes-tag' in c.attrs) || null) : null; }
+  get firstChild() { return this.children[0] || null; }
+}
+
+function makeHall() {
+  const navIds = ['home', 'roadmap', 'goals', 'goal-map', 'work', 'board-room', 'economy', 'ranks', 'collab', 'roster', 'profile'];
+  const nav = navIds.map((id) => { const a = new El('a'); a.id = 'nav-' + id; a.className = 'nav-item'; return a; });
+  const appBody = new El('div');
+  const topbar = new El('header'); topbar.id = 'app-topbar';
+  appBody.appendChild(topbar);
+  const root = { dataset: {} };
+  const document = {
+    documentElement: root,
+    createElement: (t) => new El(t),
+    querySelector: (sel) => (sel === '.app-body' ? appBody : null),
+    querySelectorAll: (sel) => (sel === '#app-sidebar .nav-item--asleep' ? nav.filter((a) => a.classList.contains('nav-item--asleep')) : []),
+    getElementById: (id) => nav.find((a) => a.id === id) || appBody.children.find((c) => c.id === id) || null,
+  };
+  return { document, nav, appBody, root };
+}
+
+// The REAL escaper and the real wake map are sliced out of shell.js with the function,
+// so the band's escaping is the shell's own, not a stand-in that agrees with the test.
+function sliceFn(name) {
+  const start = SHELL.indexOf('  function ' + name + '(');
+  const end = SHELL.indexOf('\n  }\n', start);
+  assert.ok(start > -1 && end > start, name + ' was located in shell.js');
+  return SHELL.slice(start, end + 4);
+}
+function loadApplyFounding(document, access, brand = { identity: { productName: 'Kestrel' } }) {
+  const wakeStart = SHELL.indexOf('  var WAKE_TEXT = {');
+  const wakeEnd = SHELL.indexOf('};', wakeStart) + 2;
+  assert.ok(wakeStart > -1, 'WAKE_TEXT was located in shell.js');
+  const src = [SHELL.slice(wakeStart, wakeEnd), sliceFn('esc'), sliceFn('applyFounding')].join('\n');
+  return new Function('document', 'brand', 'access', `${src}\nreturn applyFounding;`)(document, brand, access);
+}
+
+const snapshot = (h) => JSON.stringify({
+  root: h.root.dataset,
+  body: h.appBody.children.map((c) => c.id),
+  nav: h.nav.map((a) => ({ id: a.id, cls: a.className, data: a.dataset, kids: a.children.length })),
+});
+
+test('THE NO-HIJACK CONDITION: a hall that is not founding is untouched', () => {
+  const h = makeHall();
+  const before = snapshot(h);
+  const access = { founding: null };
+  loadApplyFounding(h.document, access)();
+  assert.equal(snapshot(h), before, 'null founding changes nothing at all');
+});
+
+test('not founding touches NO node — the document is never even queried', () => {
+  // Stronger than "ends up the same": a page that never wore the mode is not read.
+  const h = makeHall();
+  const touched = [];
+  const spy = new Proxy(h.document, {
+    get(t, k) { if (k !== 'documentElement') touched.push(String(k)); return t[k]; },
+  });
+  loadApplyFounding(spy, { founding: null })();
+  loadApplyFounding(spy, { founding: { active: false } })();
+  assert.deepEqual(touched, [], 'no DOM method was called');
+});
+
+test('founding ON: the band above the topbar, and the rooms the server named asleep', () => {
+  const h = makeHall();
+  const now = new Date('2026-10-09T12:00:00Z');
+  const access = { founding: fm.shapeFoundingMode({ active: 'true', stage: 'strategize', startedAt: '2026-10-01T09:00:00Z' }, now) };
+  loadApplyFounding(h.document, access)();
+  assert.equal(h.root.dataset.founding, 'on');
+  const band = h.appBody.children[0];
+  assert.equal(band.id, 'founding-band', 'the band is the first child of .app-body, above the topbar');
+  assert.equal(h.appBody.children[1].id, 'app-topbar', 'the topbar itself is kept, not replaced');
+  assert.match(band.innerHTML, /Project founding mode/);
+  assert.match(band.innerHTML, /Kestrel is still being founded/);
+  assert.match(band.innerHTML, /stage 2 of 5 · strategize · day 9/);
+  const byId = (id) => h.nav.find((a) => a.id === 'nav-' + id);
+  assert.ok(!byId('goals').classList.contains('nav-item--asleep'), 'scope is behind: goals is awake');
+  assert.ok(byId('work').classList.contains('nav-item--asleep'), 'strategize is current: tasks still sleeps');
+  assert.equal(byId('work').children[0].textContent, 'opens after strategy', 'a sentence, never a raw slug');
+  assert.equal(byId('collab').children[0].textContent, 'opens when alive');
+  assert.ok(!byId('home').classList.contains('nav-item--asleep'), 'home is never put to sleep');
+});
+
+test('founding OFF after ON restores the hall exactly — OFF removes, it does not hide', () => {
+  const h = makeHall();
+  const before = snapshot(h);
+  const access = { founding: fm.shapeFoundingMode({ active: 'true', stage: 'decide' }) };
+  const apply = loadApplyFounding(h.document, access);
+  apply();
+  assert.notEqual(snapshot(h), before);
+  access.founding = null;
+  apply();
+  assert.equal(snapshot(h), before, 'band, asleep classes, wake tags and the root attribute are all gone');
+});
+
+test('the band escapes what it prints — a project name cannot inject markup', () => {
+  const h = makeHall();
+  const access = { founding: Object.assign(fm.shapeFoundingMode({ active: 'true', stage: 'scope' }), { waiting_on: ['<img src=x onerror=1>'] }) };
+  loadApplyFounding(h.document, access, { identity: { productName: '<script>alert(1)</script>' } })();
+  const html = h.appBody.children[0].innerHTML;
+  assert.ok(!html.includes('<script>'), 'the name is escaped');
+  assert.ok(!html.includes('<img'), 'the waiting-on names are escaped');
+  assert.match(html, /&lt;script&gt;/);
+});
+
+test('who the stage close is waiting on shows in the band when the server sends it', async () => {
+  const f = await fm.foundingModeFor({
+    getSetting: async (k) => ({ [fm.KEYS.ACTIVE]: { value: 'true' }, [fm.KEYS.STAGE]: { value: 'charter' } }[k] || null),
+    waitingOnFor: async (stage) => (stage === 'charter' ? ['Avery', 'Jordan'] : []),
+  });
+  assert.deepEqual(f.waiting_on, ['Avery', 'Jordan']);
+  const h = makeHall();
+  loadApplyFounding(h.document, { founding: f })();
+  assert.match(h.appBody.children[0].innerHTML, /waiting on Avery, Jordan/);
+});
+
+test('waiting-on reads the government port\'s genesis-stage status, sitting stages only', async () => {
+  const gov = {
+    genesisStageStatus: async () => ({ stages: [
+      { key: 'scope', state: 'passed', waiting_on: [] },
+      { key: 'charter', state: 'sitting', waiting_on: [{ display_name: 'Avery' }, { github_login: 'jordan' }] },
+      { key: 'legalize', state: 'not_put', waiting_on: [] },
+    ] }),
+  };
+  const read = (stage) => fm.foundingModeFor({
+    getSetting: async (k) => ({ [fm.KEYS.ACTIVE]: { value: 'true' }, [fm.KEYS.STAGE]: { value: stage } }[k] || null),
+    government: gov,
+  });
+  assert.deepEqual((await read('charter')).waiting_on, ['Avery', 'jordan']);
+  assert.equal((await read('scope')).waiting_on, null, 'a passed stage waits on nobody');
+  assert.equal(fm.waitingOnFromGovernment({}), null, 'a port without the read offers none');
+  assert.equal((await fm.foundingModeFor({
+    getSetting: async (k) => ({ [fm.KEYS.ACTIVE]: { value: 'true' } }[k] || null), government: null,
+  })).waiting_on, null, 'no government module: the mode still reads, without names');
+});
+
+test('a failing waiting-on source never turns the mode off', async () => {
+  const f = await fm.foundingModeFor({
+    getSetting: async (k) => ({ [fm.KEYS.ACTIVE]: { value: 'true' }, [fm.KEYS.STAGE]: { value: 'scope' } }[k] || null),
+    waitingOnFor: async () => { throw new Error('government down'); },
+  });
+  assert.equal(f.active, true);
+  assert.equal(f.waiting_on, null);
+});
+
+test('re-applying ON does not stack a second band or duplicate wake tags', () => {
+  const h = makeHall();
+  const access = { founding: fm.shapeFoundingMode({ active: 'true', stage: 'decide' }) };
+  const apply = loadApplyFounding(h.document, access);
+  apply(); apply();
+  assert.equal(h.appBody.children.filter((c) => c.id === 'founding-band').length, 1);
+  assert.equal(h.nav.find((a) => a.id === 'nav-work').children.length, 1);
+});
+
+// ── the wiring ──────────────────────────────────────────────────────────────
+
+test('only an explicit active:true turns the mode on', () => {
+  const fn = SHELL.slice(SHELL.indexOf('  function applyFounding()'));
+  assert.match(fn.slice(0, 400), /f && f\.active === true/);
+});
+
+test('/me carries founding_mode from the onboarding port, fail-open to null', () => {
+  assert.match(ME, /founding_mode: foundingMode/);
+  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\)/);
+});
+
+test('BOTH applyAccess callers pass it, or the index would never show the band', () => {
+  assert.match(SHELL, /founding: me\.founding_mode \|\| null/);
+  assert.match(HALL_RENDER, /founding: \(ctx\.lastMeState && ctx\.lastMeState\.founding_mode\) \|\| null/);
+});
+
+test('founding mode adds no page, no route and no nav item — it is a mode', () => {
+  const nav = SHELL.slice(SHELL.indexOf('var NAV = ['), SHELL.indexOf('var NAV_COLLAPSE_KEY'));
+  assert.ok(!/founding|genesis/i.test(nav), 'the NAV model must not grow a founding entry');
+  const hall = fs.readdirSync(path.join(ROOT, 'modules', 'hall-ui', 'public'));
+  assert.ok(!hall.some((f) => /^founding\./.test(f)), 'no founding page file');
+});

package/tests/hall_tweak_editor.mjs

@@ -635,7 +635,7 @@ try {
     assert.match(HTML, /<body data-page="tweak-editor"[^>]*data-fullscreen-switch/);
     assert.equal((HTML.match(/<h1\b/g) || []).length, 1);
     assert.ok(HTML.indexOf('tweak-editor-lib.js') < HTML.indexOf('tweak-editor.js?'), 'the lib loads first');
-    assert.match(HTML, /shell\.js\?v=2026-09-30-commands/);
+    assert.match(HTML, /shell\.js\?v=2026-09-30-founding-commands/);
     assert.equal(/fonts\.googleapis\.com\/css/.test(HTML), false);
     for (const id of ['tw-bar', 'tw-counter', 'tw-open', 'tw-open-more', 'tw-divider', 'tw-openwrap', 'tw-open-menu', 'tw-open-tab', 'tw-open-split', 'tw-frame', 'tw-frame-view', 'tw-split-close', 'tw-download', 'tw-upload', 'tw-file', 'tw-submit', 'tw-paper', 'tw-doc', 'tw-notice', 'tw-done', 'tw-take', 'tw-pick', 'tw-picks', 'tw-refused', 'tw-refused-title', 'tw-refused-list', 'tw-refused-next', 'tw-refused-download', 'tw-refused-close']) {
       assert.ok(new RegExp(`id="${id}"`).test(HTML), `#${id} is in the markup`);

package/tests/nav_permission_atoms.mjs

@@ -87,7 +87,7 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 // the file and left the query alone, so a returning browser kept the cached copy —
 // a fix that reaches nobody looks identical to a fix that does not work.
 
-const SHELL_SHA = '4e14115a3737db9a';
+const SHELL_SHA = '3e4f905947bc39d2';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);