@bongos/core 1.19.622 → 1.19.624

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

@@ -30,7 +30,7 @@
   // Anchors must stay in step with their source of truth; the test asserts it:
   //   standing   → builders.js STANDING_GROUPS (+ shell.js VIEW_ALIASES)
   //   work       → work.js makeTabs ids
-  //   government → government.js makeTabs ids (the R15 three-section IA)
+  //   government → government.js makeTabs ids (two rooms since ADR 0266)
   //   settings   → settings.js RAIL_GROUPS
   var SECTIONS = [
     { parent: 'Standing', gate: 'nav-standing', items: [
@@ -45,9 +45,12 @@
       { label: 'Backlog', href: '/work#backlog' },
       { label: 'Completed', href: '/work#completed' },
     ] },
+    // Two entries, not three: the Board Room is a PAGE since ADR 0266, so it is
+    // read live from the sidebar like every other page and must not be declared
+    // here as well — a sub-destination and a page of the same name would offer
+    // the reader two rows to the same room.
     { parent: 'Government', gate: 'nav-government', items: [
       { label: 'Constitution', href: '/government#constitution' },
-      { label: 'Board Room', href: '/government#board-room' },
       { label: 'Ranks & Permissions', href: '/government#ranks' },
     ] },
     { parent: 'Settings', gate: 'shell-user', items: [

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

@@ -246,6 +246,22 @@
     // Archon-only, so a group header reading "Archon" over items a Metic can open
     // would misdescribe the ladder to the builders most likely to be learning it.
     { group: 'Government', gate: 'government', items: [
+      // FIRST in the group because it is the one page here you ACT on — the
+      // Community group's ordering rule, applied (a sitting waits on a decision;
+      // the rest of this group is monitoring). Carved out of the /government tab
+      // strip by ADR 0266, which is also why it needs its own item at all: while
+      // it was a tab, the group's only door to it was labelled "Permissions".
+      //
+      // THE GATE HERE IS COSMETIC AND DELIBERATELY CONSERVATIVE. The page's real
+      // wall is `board.vote.cast` (auth.js requireBoardVotePage), which floors at
+      // xenos so a widened board can reach the room. This nav gate cannot say
+      // that: gateAllows() speaks rank, not permission. It is set to the group's
+      // floor because today's constitution seats `rank:archon`, so no sub-Metic
+      // member exists to hide the link from. An instance that widens membership
+      // below Metic gets a room it can reach by URL and by the board_votes need's
+      // deep link, but no sidebar entry — teaching the shell a permission-aware
+      // gate is filed rather than guessed at here.
+      { id: 'board-room', label: 'Board Room', icon: 'admin', href: '/board-room', gate: 'government' },
       { id: 'watch', label: 'Watch', icon: 'admin', href: '/watch', gate: 'government' },
       { id: 'harbor', label: 'Harbor', icon: 'admin', href: '/harbor', gate: 'government', module: 'dev-box' },
       { id: 'gate', label: 'Gate', icon: 'admin', href: '/gate', gate: 'government' },

package/modules/sessions/db.js

@@ -109,6 +109,52 @@ async function upsertSessionRecord(opts) {
   return upsertSessionRecordTx(pool, opts);
 }
 
+// syncSessionDrachmaeEarnedTx — re-derive session_records.drachmae_earned from
+// the ledger (task 1003634). Returns the synced value, or null if there was no
+// row to sync (or economy is disabled).
+//
+// The column means "the credit_log delta attributable to this session"
+// (migration 062), but the only thing that ever wrote it was the route's
+// sumCreditsForTasks(), which sums rows keyed on `task_id`. The cost-plus session
+// reward keys on `session_id` and leaves task_id NULL deliberately, because it
+// pays for the session's real token spend rather than for any one task in it. So
+// the mirror could not see it. Under reward mode 'cost-plus-only' (ADR 0146 —
+// this instance's standing choice) that reward is the ONLY stream that pays, so
+// the figure was structurally 0 for every session, and the hall told builders
+// they had earned nothing for work they were genuinely paid for. A builder
+// reported it as missing pay; the pay was never missing, this number was.
+//
+// It asks economy for the total over BOTH attribution keys and SETS it, rather
+// than adding a delta. That is what makes it idempotent and safe to call from
+// every trigger: the sum covers the row's ACCUMULATED task_ids (set-unioned
+// across every upload the session has made) plus its session_id, so it already
+// describes the whole session however many times it runs. Re-running can only
+// land on the same number, which is why calling it on an already-paid session is
+// a repair rather than a double-count.
+async function syncSessionDrachmaeEarnedTx(client, builderId, sessionId) {
+  const reward = seams.resolveOptional('reward');
+  if (!reward || !sessionId) return null;
+  // The row's task_ids are read back rather than taken from the caller: the
+  // upsert set-unions them, and the two deferred triggers never had them at all.
+  const { rows } = await client.query(
+    `SELECT task_ids FROM session_records WHERE session_id = $1 AND builder_id = $2`,
+    [sessionId, builderId]
+  );
+  if (rows.length === 0) return null;
+  const ids = Array.isArray(rows[0].task_ids)
+    ? rows[0].task_ids.map((n) => Number(n)).filter(Number.isFinite)
+    : [];
+  const earned = await reward.sumSessionEarnings(client, builderId, ids, sessionId);
+  const { rows: synced } = await client.query(
+    `UPDATE session_records
+        SET drachmae_earned = $3
+      WHERE session_id = $1 AND builder_id = $2
+      RETURNING drachmae_earned`,
+    [sessionId, builderId, Math.trunc(Number(earned) || 0)]
+  );
+  return synced.length > 0 ? synced[0].drachmae_earned : null;
+}
+
 // awardSessionTokenRewardTx — resolve the economy `reward` port and book the
 // idempotent cost-plus session token reward on `client`, mirroring the granted
 // drachmae onto the session_records row for observability (the authoritative
@@ -137,6 +183,19 @@ async function awardSessionTokenRewardTx(client, { builderId, sessionId, modelUs
       [sessionId, tokenReward.drachmae, builderId]
     );
   }
+  // Sync the earnings mirror on EVERY attempt, not only a fresh award. The
+  // watermark makes a re-attempt on an already-paid session a clean no-op for the
+  // money, and this is where that no-op earns its keep: it still repairs a row
+  // whose drachmae_earned was written by the old task_id-only sum. Since all
+  // three pay-on-land triggers funnel through here, one call site covers the
+  // upload-time gate, the task.shipped listener, and the state-based sweep.
+  const sessionDrachmaeEarned = await syncSessionDrachmaeEarnedTx(client, builderId, sessionId);
+  // Ride the synced figure back on the result so a caller holding a pre-sync
+  // record can refresh it — otherwise POST /sessions echoes the stale 0 it was
+  // handed even though the row is now correct.
+  if (tokenReward && sessionDrachmaeEarned !== null) {
+    tokenReward.sessionDrachmaeEarned = sessionDrachmaeEarned;
+  }
   return tokenReward;
 }
 
@@ -186,6 +245,12 @@ async function upsertSessionRecordWithReward(opts) {
           totalTokens: opts.totalTokens || 0,
         });
       }
+      // The upsert wrote the figure the route computed BEFORE this transaction
+      // booked anything; the award has since re-derived it. Adopt it so the
+      // response matches the row.
+      if (tokenReward && tokenReward.sessionDrachmaeEarned != null) {
+        record.drachmae_earned = tokenReward.sessionDrachmaeEarned;
+      }
     }
     return record ? { ...record, tokenReward } : null;
   });

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.622",
+  "version": "1.19.624",
   "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/scripts/gds/backfill-session-earnings.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+'use strict';
+
+// scripts/gds/backfill-session-earnings.js — repair the historical
+// `session_records.drachmae_earned` mirror (task 1003634).
+//
+// WHAT THIS IS, and what it emphatically is NOT. It moves NO money. It writes no
+// `credit_log` row, mints nothing, and cannot change any builder's balance. It
+// rewrites ONE display column to agree with the ledger that already exists. That
+// makes it categorically unlike its neighbours here (backfill-task-rewards.js,
+// backfill-subagent-rewards.js), which mint credits and carry an ADR 0097 /
+// ADR 0173 safety model to match. Read this one as a data repair.
+//
+// WHY IT IS NEEDED. `drachmae_earned` means "the credit_log delta attributable to
+// this session" (migration 062), but the only thing that ever wrote it summed
+// rows keyed on `task_id`. The cost-plus session reward (ADR 0054) keys on
+// `session_id` and leaves `task_id` NULL on purpose, because it pays for the
+// session's real token spend rather than for any one task in it. So the mirror
+// could not see it. Under reward mode `cost-plus-only` (ADR 0146 — this
+// instance's standing choice) that reward is the ONLY stream that pays, so the
+// column read 0 for essentially every session, and the hall told builders they
+// had earned nothing for work they had genuinely been paid for. A builder
+// reported it as missing pay; the pay was never missing, this number was.
+//
+// WHY THE LIVE FIX DOES NOT COVER HISTORY. The code fix re-derives the figure
+// whenever a reward books, and all three pay-on-land triggers now funnel through
+// that. But none of them revisits a session that is already paid in full — the
+// state-based sweep explicitly skips any session that already has a
+// `session.token_reward` row. So already-paid history never self-heals, which is
+// precisely the history a builder looks at. Hence a one-shot pass.
+//
+// SAFETY. DRY-RUN BY DEFAULT: with no flags it prints the plan and writes
+// nothing. `--apply` performs the UPDATEs. Idempotent by construction — every
+// row is SET to a value derived wholly from current ledger state, so re-running
+// lands on the same numbers, and a row already correct is skipped and reported
+// as such. `--builder N` scopes the pass to one builder (useful for verifying on
+// a single account before the full sweep).
+//
+// Run:  node scripts/gds/backfill-session-earnings.js [--builder N] [--limit N]
+//       node scripts/gds/backfill-session-earnings.js --apply
+
+const path = require('node:path');
+
+const credits = require('../../modules/economy/credits');
+const { arg, hasFlag } = require('./cli-lib');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+
+function loadPool() {
+  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  return pool;
+}
+
+async function main() {
+  const apply = hasFlag('--apply');
+  const builderArg = arg('--builder');
+  const limitArg = Number(arg('--limit'));
+  const limit = Number.isFinite(limitArg) && limitArg > 0 ? Math.trunc(limitArg) : null;
+
+  const pool = loadPool();
+  const client = await pool.connect();
+  let changed = 0;
+  let alreadyCorrect = 0;
+  let scanned = 0;
+  let deltaTotal = 0;
+  const examples = [];
+
+  try {
+    const params = [];
+    let where = 'WHERE sr.session_id IS NOT NULL';
+    if (builderArg) { params.push(builderArg); where += ` AND sr.builder_id = $${params.length}`; }
+    let sql = `SELECT sr.session_id, sr.builder_id, sr.task_ids, sr.drachmae_earned,
+                      b.github_login
+                 FROM session_records sr
+                 JOIN builders b ON b.id = sr.builder_id
+                 ${where}
+                ORDER BY sr.uploaded_at DESC`;
+    if (limit) { params.push(limit); sql += ` LIMIT $${params.length}`; }
+
+    const { rows } = await client.query(sql, params);
+    scanned = rows.length;
+
+    for (const r of rows) {
+      const ids = Array.isArray(r.task_ids)
+        ? r.task_ids.map((n) => Number(n)).filter(Number.isFinite)
+        : [];
+      // The same two-key sum the live path uses — one definition, so a repaired
+      // row and a freshly-synced row can never disagree.
+      const truth = await credits.sumSessionEarnings(client, r.builder_id, ids, r.session_id);
+      const was = Number(r.drachmae_earned) || 0;
+      if (truth === was) { alreadyCorrect++; continue; }
+      changed++;
+      deltaTotal += (truth - was);
+      if (examples.length < 15) {
+        examples.push(`  ${String(r.github_login).padEnd(18)} ${r.session_id.slice(0, 8)}  ${was} → ${truth}`);
+      }
+      if (apply) {
+        await client.query(
+          `UPDATE session_records SET drachmae_earned = $3
+            WHERE session_id = $1 AND builder_id = $2`,
+          [r.session_id, r.builder_id, truth]
+        );
+      }
+    }
+  } finally {
+    client.release();
+    await pool.end().catch(() => {});
+  }
+
+  console.log(`\nsession-earnings backfill — ${apply ? 'APPLIED' : 'DRY RUN (no writes)'}`);
+  console.log(`  sessions scanned    ${scanned}`);
+  console.log(`  already correct     ${alreadyCorrect}`);
+  console.log(`  ${apply ? 'repaired' : 'would repair'}${apply ? '            ' : '        '}${changed}`);
+  console.log(`  net mirror change   ${deltaTotal >= 0 ? '+' : ''}${deltaTotal} drachmae of DISPLAY (no money moved)`);
+  if (examples.length > 0) {
+    console.log(`\n  sample rows:\n${examples.join('\n')}`);
+  }
+  if (!apply && changed > 0) {
+    console.log(`\n  re-run with --apply to write these.`);
+  }
+}
+
+main().catch((err) => { console.error(err); process.exit(1); });

package/scripts/gds/fitness-checks-vocabulary.js

@@ -59,6 +59,13 @@ const VOCAB_SURFACE = [
   'modules/hall-ui/public/government.js',
   'modules/hall-ui/public/government.html',
   'modules/hall-ui/public/government.css',
+  // ADR 0266 carved the Board Room out of government.js onto its own page. The
+  // wall follows the SURFACE, not the filename — without these two rows the
+  // room's own files would have left the wall's scope, which is how a renamed
+  // file quietly drops an enforcement it used to be held to.
+  'modules/hall-ui/public/board-room.js',
+  'modules/hall-ui/public/board-room.html',
+  'modules/hall-ui/public/board-room.css',
 ];
 const VOCAB_EXTS = new Set(['.js', '.json', '.html', '.css']);
 const VOCAB_BANNED = [

package/scripts/gds/run-unit-tests.js

@@ -106,6 +106,13 @@ const INTEGRATION = new Set([
   // parses this set out of the source, so a quoted word in a comment reads as an
   // entry — the same reason the copy_desk_flags_db note above is worded that way.)
   'idea_credit_streams_db',
+  // task 1003634: the session earnings mirror against real SQL. The defect was
+  // never arithmetic — it was which credit_log rows a WHERE clause can reach, so
+  // a stubbed client would answer exactly the assumption under test. Here the
+  // two-key predicate meets a real planner, and the first test asserts the OLD
+  // predicate still returns 0 so the bug itself stays executable. Same
+  // always-rolled-back transaction discipline as the entry above.
+  'session_earnings_mirror_db',
   // RENAMED by ADR 0174 (goal 1000068) — these entries said governance_* until task
   // 1003091. A curated set keyed by a stem that no longer exists silently stops
   // covering its file: both of these dropped OUT of the integration set and INTO the

package/src/bongos/auth.js

@@ -401,6 +401,21 @@ const PAGE_GATES = Object.freeze({
   requireProjectCuratePage: Object.freeze({
     permission: 'project.curate', deniedTo: '/builders', alsoAdmits: 'isProjectOwner',
   }),
+  // The /board-room page (ADR 0266) — gated on `board.vote.cast`, the SAME atom
+  // the vote route checks, so the surface's reach equals the right to vote.
+  //
+  // That atom floors at XENOS on purpose (modules/government/board.js — low so
+  // that WIDENING the board works), which makes this the widest page gate in the
+  // table. It is deliberate and it is not a hole: the floor is the coarse gate,
+  // and MEMBERSHIP is still checked in-handler per item against that item's own
+  // snapshotted constitution. A holder who sits on no board sees the room and no
+  // ballot — the honest state, since ADR 0175 §9 made the ballot open on purpose.
+  //
+  // Reaching for `page.view.government` (metic+) instead would look tighter and
+  // be wrong: an instance that widens membership below Metic would then have
+  // members who can cast a vote through the API and cannot load the page they
+  // would cast it on. That is the code-path change ADR 0175 §6 exists to remove.
+  requireBoardVotePage: Object.freeze({ permission: 'board.vote.cast', deniedTo: '/builders' }),
 });
 
 // The `alsoAdmits` door — "is this visitor the page's OTHER audience?", asked of
@@ -550,6 +565,17 @@ async function requireProjectCuratePage(req, res, next) {
   return runPageGate('requireProjectCuratePage', req, res, next);
 }
 
+// The /board-room page (ADR 0266) — gated on the `board.vote.cast` ATOM, the
+// same key the vote route checks, so the page layer can never drift NARROWER
+// than the API it fronts. That is the direction that matters here: the Board
+// Room used to live inside /government behind `page.view.government` (metic+)
+// while the vote atom floors at xenos, so a widened board produced members who
+// could vote by API and not load the page. See PAGE_GATES above for why the
+// wide floor is correct rather than a hole (membership is the in-handler check).
+async function requireBoardVotePage(req, res, next) {
+  return runPageGate('requireBoardVotePage', req, res, next);
+}
+
 // The orientation reading rooms (the citizen's primer, the system-maps/diagrams)
 // that #766 closed to newcomers and #770 enforces at the URL. A Xenos's path is
 // action-only — find work, claim, ship three — so these pages are reserved for
@@ -821,6 +847,7 @@ module.exports = {
   requireGovernmentManagePage,
   requireNonXenosPage,
   requireProjectCuratePage,
+  requireBoardVotePage,
   requireRank,
   rankMeetsThreshold,
   requirePermission,

package/src/bongos/serve-internal.js

@@ -844,6 +844,21 @@ function mountInternalSurfaces(app) {
   // the `government.manage` atom itself (archon), the same key its data routes
   // check — requireGovernmentManagePage, not the metic-floored gate above.
   const GOVERNMENT_PAGE_RE = /^\/builders\/government(?:\.html)?\/?$/;
+  // /board-room — the Board Room, carved out of the /government tab strip onto
+  // its own page (ADR 0266). It does NOT take the gate above. Its atom is
+  // `board.vote.cast`, the same key the vote route checks, so the page's reach
+  // equals the right to vote: that atom floors at xenos on purpose, so that a
+  // constitution widening membership below Metic gets members who can actually
+  // reach the room rather than members who can only vote by curl. Membership is
+  // still the in-handler check, per item, against that item's own snapshotted
+  // constitution.
+  //
+  // NB as at PROJECT_SETTINGS_PAGE_RE: this assignment must stay
+  // `const NAME_RE = /…/;` with nothing between the `=` and the literal —
+  // tests/hall_page_gate_map.mjs rebuilds the URL→gate map by parsing this file
+  // statically, and a comment in that gap drops the regex out of the map, which
+  // makes the page test as UNGATED while looking gated here. Prose goes above.
+  const BOARD_ROOM_PAGE_RE = /^\/builders\/board-room(?:\.html)?\/?$/;
   // The /people builder directory (task 1002577): gated on `project.curate`, the
   // exact permission its data route (GET /scouting) checks — same posture as the
   // /government tab above (the page can never drift wider than the API it fronts).
@@ -885,6 +900,12 @@ function mountInternalSurfaces(app) {
     if (GOVERNMENT_PAGE_RE.test(norm)) {
       return gdsAuth.requireGovernmentPage(req, res, next);
     }
+    // ADR 0266: the Board Room's own page, on the vote atom rather than the
+    // government page floor. Ordered after the branch above only for reading
+    // order — the regexes are disjoint, so the sequence carries no meaning.
+    if (BOARD_ROOM_PAGE_RE.test(norm)) {
+      return gdsAuth.requireBoardVotePage(req, res, next);
+    }
     if (PEOPLE_PAGE_RE.test(norm)) {
       return gdsAuth.requireProjectCuratePage(req, res, next);
     }

package/src/module-api.js

@@ -55,7 +55,7 @@ const { buildInfo } = require('./build-info');
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.622'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.624'; // 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('dev-box'); log.info('mounted');

package/tests/auth_resolve_failure.mjs

@@ -94,16 +94,17 @@ test('AUDIT: every async middleware mounted directly on a router owns its reject
   //   requireBuilder            — the API gate. Guarded here (BV1.R109-follow-up).
   //   requireBuilderPage         \
   //   requireGovernmentPage       \
-  //   requireGovernmentManagePage  > all five delegate to runPageGate, guarded by BV1.R107.
-  //   requireNonXenosPage         /  (the R113 roles-tab gate; the /people curate gate)
-  //   requireProjectCuratePage   /
+  //   requireGovernmentManagePage  \ all SIX delegate to runPageGate, guarded by BV1.R107.
+  //   requireNonXenosPage          /  (the R113 roles-tab gate; the /people curate
+  //   requireProjectCuratePage    /    gate; the ADR 0266 /board-room vote gate)
+  //   requireBoardVotePage       /
   // Anything else async and router-mounted must be added with its own try/catch.
   const src = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'auth.js'), 'utf8');
   const asyncMw = [...src.matchAll(/^async function (require\w+|allow\w+)\s*\(req, res, next\)/gm)].map((m) => m[1]);
-  assert.deepEqual(asyncMw.sort(), ['requireBuilder', 'requireBuilderPage', 'requireGovernmentManagePage', 'requireGovernmentPage', 'requireNonXenosPage', 'requireProjectCuratePage'],
+  assert.deepEqual(asyncMw.sort(), ['requireBoardVotePage', 'requireBuilder', 'requireBuilderPage', 'requireGovernmentManagePage', 'requireGovernmentPage', 'requireNonXenosPage', 'requireProjectCuratePage'],
     'a new async router middleware appeared — give it a try/catch and add it here');
   // The page gates must actually delegate (that is WHY they are safe).
-  for (const name of ['requireBuilderPage', 'requireGovernmentPage', 'requireGovernmentManagePage', 'requireNonXenosPage', 'requireProjectCuratePage']) {
+  for (const name of ['requireBuilderPage', 'requireGovernmentPage', 'requireGovernmentManagePage', 'requireNonXenosPage', 'requireProjectCuratePage', 'requireBoardVotePage']) {
     const fn = src.slice(src.indexOf(`async function ${name}`));
     assert.match(sliceFn(fn), /runPageGate\(/, `${name} must delegate to the guarded runPageGate`);
   }

package/tests/builder_needs.mjs

@@ -209,5 +209,127 @@ t('the /me aggregator feeds computeNeeds the founder facts under their contract
   assert.match(src, /getFoundingBuilder\(\)/, 'me.js must resolve the founder row');
 });
 
+// ---- two needs at once (task 1003738) --------------------------------------
+//
+// The defect: computeNeeds sorted by state alone with a stable sort, so within
+// the action_needed bucket the NEEDS array order decided everything — and
+// board_votes is listed fourth, behind art_key. A builder with an unset image
+// key therefore never saw a waiting board vote, on either surface, because both
+// renderers took "the first one". The fix is two-part and both parts are pinned
+// here: an explicit priority inside the bucket, and a LIST surface that renders
+// every action_needed item instead of only the loudest.
+console.log('two simultaneous action_needed needs (task 1003738):');
+
+// art_key action_needed (archon, no own key) + board_votes action_needed.
+const TWO = {
+  rank: 'archon',
+  ownKeySet: false,
+  pendingBoardVotes: { count: 2, first_item_id: 12 },
+};
+
+t('both needs are action_needed — the fixture really does collide', () => {
+  const r = needs.computeNeeds(TWO);
+  const ids = r.items.filter((n) => n.state === 'action_needed').map((n) => n.id);
+  assert.ok(ids.includes('art_key'), 'art_key must be action_needed here');
+  assert.ok(ids.includes('board_votes'), 'board_votes must be action_needed here');
+  assert.equal(r.action_needed_count, 2);
+});
+
+t('the board vote outranks the art key — someone else is blocked on it', () => {
+  const r = needs.computeNeeds(TWO);
+  assert.equal(r.items[0].id, 'board_votes',
+    'a need others are blocked on must lead; registry order must not decide');
+});
+
+t('priority is NOT severity — severity would have kept the bug', () => {
+  // The trap worth pinning: art_key is severity 'action' and board_votes is
+  // 'info', so ordering the bucket by severity would have left the art key
+  // first and the board vote hidden. If someone "simplifies" the weight map
+  // into a severity sort, this fails.
+  const r = needs.computeNeeds(TWO);
+  const art_ = r.items.find((n) => n.id === 'art_key');
+  const board = r.items.find((n) => n.id === 'board_votes');
+  assert.equal(art_.severity, 'action');
+  assert.equal(board.severity, 'info');
+  assert.ok(needs.NEED_PRIORITY.board_votes < needs.NEED_PRIORITY.art_key,
+    'the weight map, not severity, is what orders the bucket');
+});
+
+t('an unweighted need sorts last in its bucket, never first', () => {
+  // Appending to NEEDS without adding a weight must not silently take the lead.
+  const items = [{ id: 'brand_new', state: 'action_needed' }, { id: 'board_votes', state: 'action_needed' }];
+  const order = { action_needed: 0, covered: 1, satisfied: 2 };
+  const weight = (n) => needs.NEED_PRIORITY[n.id] ?? 99;
+  items.sort((a, b) => ((order[a.state] ?? 9) - (order[b.state] ?? 9)) || (weight(a) - weight(b)));
+  assert.equal(items[0].id, 'board_votes');
+});
+
+t('the founding welcome still leads during the grace', () => {
+  // The weight tie-break must not demote the welcome: before this task it was
+  // first only because unshift + a stable sort put it there.
+  const r = needs.computeNeeds({
+    ...TWO, isFoundingOwner: true, founderCreatedAt: new Date().toISOString(), projectName: 'Mercury',
+  });
+  assert.equal(r.items[0].id, 'founding_welcome');
+  assert.equal(r.has_action_needed, false);
+});
+
+// ---- the rendered output ----------------------------------------------------
+//
+// renderSystemNotices lives inside hall-render.js's IIFE, so it cannot be
+// imported — but it only touches `document`, `escapeHtml` and `window`, so the
+// real shipped function is sliced out and RUN here (the repo's "run it rather
+// than grep it" preference) rather than asserted against by regex. A grep would
+// pass on a comment; this fails if the board vote is not in the HTML.
+function runSystemNotices(args) {
+  const src = readFileSync(path.join(ROOT, 'modules/hall-ui/public/hall-render.js'), 'utf8');
+  const start = src.indexOf('function renderSystemNotices');
+  assert.ok(start > 0, 'renderSystemNotices must still exist in hall-render.js');
+  // Anchor on the BODY brace, not the first '{' — the signature destructures
+  // its argument, so the first brace closes the parameter list.
+  const argsEnd = src.indexOf(') {', start);
+  assert.ok(argsEnd > start, 'renderSystemNotices signature changed shape');
+  let i = src.indexOf('{', argsEnd);
+  let depth = 0;
+  let end = -1;
+  for (; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}') { depth--; if (depth === 0) { end = i + 1; break; } }
+  }
+  assert.ok(end > start, 'could not slice renderSystemNotices');
+  const box = { innerHTML: '' };
+  const doc = { getElementById: (id) => (id === 'attention-system' ? box : null) };
+  const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  const body = src.slice(start, end);
+  const make = new Function('document', 'escapeHtml', 'window', `${body}\nreturn renderSystemNotices;`);
+  make(doc, esc, {})(args);
+  return box.innerHTML;
+}
+
+t('THE BUG: with the art key also open, the board vote is still rendered', () => {
+  const r = needs.computeNeeds(TWO);
+  const actionNeeds = r.items.filter((n) => n.state === 'action_needed');
+  const html = runSystemNotices({
+    rebaseTasks: [], need: actionNeeds[0], actionNeeds, cost: null,
+  });
+  assert.match(html, /waiting on your vote/i,
+    'the board vote must be reachable in the rendered output, not suppressed');
+  assert.match(html, /art coverage has ended/i,
+    'and the art key must not be dropped either — the list shows both');
+  assert.equal((html.match(/<li class="ginbox__item/g) || []).length, 2, 'one line per waiting need');
+});
+
+t('a single action_needed need still renders exactly one line', () => {
+  const r = needs.computeNeeds({ rank: 'thetes', ownKeySet: false });
+  const actionNeeds = r.items.filter((n) => n.state === 'action_needed');
+  const html = runSystemNotices({ rebaseTasks: [], need: actionNeeds[0], actionNeeds, cost: null });
+  assert.equal((html.match(/<li class="ginbox__item/g) || []).length, 1);
+});
+
+t('nothing waiting renders nothing at all', () => {
+  const html = runSystemNotices({ rebaseTasks: [], need: null, actionNeeds: [], cost: null });
+  assert.equal(html, '');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);