@bongos/core 1.19.623 → 1.19.624

package/docs/module-api-changelog.md

@@ -1695,5 +1695,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.621 with no explicit bump. run 34322091367. (task 1002620)
   1.19.623 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.622 with no explicit bump. run 34323141703. (task 1002620)
+  1.19.624 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.623 with no explicit bump. run 34326009063. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/builder-settings/builder-needs.js

@@ -219,6 +219,36 @@ function mingleIntroductionsNeed(ctx) {
 
 const NEEDS = [artKeyNeed, helpRequestsNeed, taskRecommendationsNeed, boardVotesNeed, mingleIntroductionsNeed];
 
+// Priority WITHIN a state bucket (task 1003738). computeNeeds used to sort by
+// state alone with a stable sort, so the NEEDS array order silently decided
+// which item a single-slot renderer showed. board_votes sits fourth, behind
+// art_key — so any builder with an unset image key never saw a waiting board
+// vote, while both renderers' comments claimed they showed "the highest-priority"
+// need. Within a bucket there was no such thing.
+//
+// NOT keyed on `severity`, which is the obvious-looking choice and the wrong
+// one: art_key is severity 'action' and board_votes is 'info', so ordering by
+// severity would have PRESERVED the exact bug this fixes. The rule here is who
+// is waiting:
+//
+//   A NEED SOMEONE ELSE IS BLOCKED ON OUTRANKS A NEED THAT ONLY AFFECTS YOU.
+//
+// A sitting cannot be decided until a member votes, and its window can expire;
+// an unset art key stops only your own art, whenever you next want it.
+//
+// Lower number = louder. An id missing from this map sorts last, so appending to
+// NEEDS without a weight is safe (it just lands at the back of its bucket).
+// founding_welcome is deliberately negative: during the founding grace the
+// roster leads with the welcome, which is what the grace is for.
+const NEED_PRIORITY = {
+  founding_welcome: -1,
+  board_votes: 0,
+  help_requests: 1,
+  art_key: 2,
+  task_recommendations: 3,
+  mingle_introductions: 4,
+};
+
 // ---- founding grace (task 1002739 / direction §5.6, idea 1000701) -----------
 //
 // A freshly-provisioned instance used to greet its founding owner with "your
@@ -265,9 +295,14 @@ function foundingWelcomeNeed(ctx) {
 // functions read (see each need's doc). Returns:
 //   { items: Need[], action_needed_count, has_action_needed }
 // items is ordered: action_needed first (loudest), then covered, then satisfied,
-// so any renderer that takes "the first one" gets the most urgent. During the
-// founding grace nothing is action_needed, so the welcome (prepended before the
-// stable sort) is what that renderer shows.
+// and WITHIN each bucket by NEED_PRIORITY above — so a renderer that takes "the
+// first one" really does get the most urgent, which before task 1003738 it did
+// not (it got whichever need NEEDS happened to list first). During the founding
+// grace nothing is action_needed, so the welcome is what that renderer shows.
+//
+// A renderer that can show a LIST should render every action_needed item rather
+// than the first: ordering decides emphasis, it does not make the rest safe to
+// drop. Home's "From the system" inbox does exactly that.
 function computeNeeds(ctx = {}) {
   const grace = foundingGraceActive(ctx);
   let items = NEEDS.map((fn) => fn(ctx)).filter(Boolean);
@@ -282,7 +317,8 @@ function computeNeeds(ctx = {}) {
     items.unshift(foundingWelcomeNeed(ctx));
   }
   const order = { action_needed: 0, covered: 1, satisfied: 2 };
-  items.sort((a, b) => (order[a.state] ?? 9) - (order[b.state] ?? 9));
+  const weight = (n) => NEED_PRIORITY[n.id] ?? 99;
+  items.sort((a, b) => ((order[a.state] ?? 9) - (order[b.state] ?? 9)) || (weight(a) - weight(b)));
   const actionNeeded = items.filter((n) => n.state === 'action_needed');
   return {
     items,
@@ -299,4 +335,5 @@ module.exports = {
   foundingGraceActive,
   FOUNDING_GRACE_DAYS,
   SETTINGS_PATH,
+  NEED_PRIORITY,
 };

package/modules/economy/credits.js

@@ -931,6 +931,43 @@ async function sumCreditsForTasks(builderId, taskIds) {
   return rows[0] ? rows[0].total : 0;
 }
 
+// sumSessionEarnings — what ONE session actually earned its builder, across BOTH
+// of the ledger's attribution keys. The authoritative answer to the question
+// session_records.drachmae_earned exists to mirror.
+//
+// Why it has to be two keys: credit_log rows reach a builder by two different
+// routes, and each stream picks exactly one. The per-task streams (the confirm
+// credit, the idea slices) key on `task_id` and leave session_id NULL. The
+// cost-plus session reward (ADR 0054) is the mirror image — it keys on
+// `session_id` and leaves task_id NULL deliberately, because it pays for the
+// SESSION's real token spend, not for any one task in it.
+//
+// sumCreditsForTasks() above sees only the first route. That was survivable while
+// every instance paid both streams, but under reward mode 'cost-plus-only'
+// (ADR 0146 — this instance's standing choice) the session reward is the ONLY
+// stream that pays, so a task_id-keyed sum is structurally always 0 and the hall
+// told every builder they had earned nothing for work they were genuinely paid
+// for (task 1003634). A builder reported it as missing pay; the money was never
+// missing, the mirror was.
+//
+// `executor` is a Pool or a tx client, so the caller can ask INSIDE the same
+// transaction that just booked the reward and see it. The OR is one predicate over
+// one scan, so a row matching both keys is summed once, not twice — the figure is
+// a pure function of ledger state and can be re-derived any number of times.
+async function sumSessionEarnings(executor, builderId, taskIds, sessionId) {
+  const ids = Array.isArray(taskIds) ? taskIds.map(Number).filter(Number.isFinite) : [];
+  const sid = sessionId == null ? null : String(sessionId);
+  if (ids.length === 0 && !sid) return 0;
+  const { rows } = await executor.query(
+    `SELECT COALESCE(SUM(delta), 0)::int AS total
+       FROM credit_log
+      WHERE builder_id = $1
+        AND (task_id = ANY($2::bigint[]) OR ($3::text IS NOT NULL AND session_id = $3))`,
+    [builderId, ids, sid]
+  );
+  return rows[0] ? rows[0].total : 0;
+}
+
 // The three ideator streams (ADR 0172) each book under a reason key that EMBEDS
 // the idea (and, for stream 1, the task) — that string IS the idempotency
 // predicate, which is why it can't be a bare constant:
@@ -1038,6 +1075,7 @@ module.exports = {
   netNegativeBonusAmount,
   awardNetNegativeBonus,
   sumCreditsForTasks,
+  sumSessionEarnings,
   // the ledger read surface (task 1003484, blocker 1000127)
   creditLedger,
   IDEA_STREAM_REASON_PREFIXES,

package/modules/economy/reward.js

@@ -73,6 +73,11 @@ module.exports = {
   getBuilderAchievements: (...a) => achievements.getBuilderAchievements(...a),
   getLockedAchievementsProgress: (...a) => achievements.getLockedAchievementsProgress(...a),
   sumCreditsForTasks: (...a) => credits.sumCreditsForTasks(...a),
+  // The two-key session earnings sum (task 1003634) — transaction-participant:
+  // the sessions module passes its tx `client` so it reads the cost-plus reward
+  // its own transaction just booked. On the port because credit_log is economy's
+  // table and sessions may only cross the wall through here (ADR 0083 / 0093 §2).
+  sumSessionEarnings: (...a) => credits.sumSessionEarnings(...a),
   // The per-row ledger read (task 1003484). On the port because the surface core
   // most wants it for is a HALL view — "what did this idea earn me" — and a core
   // route must reach economy through here, never by importing the module.

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

@@ -475,6 +475,14 @@
     const need = (needs && Array.isArray(needs.items))
       ? needs.items.find((n) => n && n.state !== 'satisfied')
       : null;
+    // task 1003738: this banner is ONE box, so it still shows one need — but the
+    // Home inbox below is a list and must not drop the rest. computeNeeds now
+    // orders the action_needed bucket by an explicit weight, so `need` above is
+    // deliberately the most urgent rather than whichever the registry listed
+    // first (which was permanently the art key, hiding waiting board votes).
+    const actionNeeds = (needs && Array.isArray(needs.items))
+      ? needs.items.filter((n) => n && n.state === 'action_needed')
+      : [];
     const needsBanner = need
       ? `<div class="profile__needs profile__needs--${need.state === 'action_needed' ? 'action' : 'covered'}" role="status">
            <strong>${escapeHtml(need.title)}</strong> — ${escapeHtml(need.message)}
@@ -576,7 +584,7 @@
     }
     const homeStandingSection = document.getElementById('home-standing');
     if (homeStandingSection && !ctx.newcomerGated) homeStandingSection.hidden = false;
-    renderSystemNotices({ rebaseTasks, need, cost });
+    renderSystemNotices({ rebaseTasks, need, actionNeeds, cost });
   }
 
   // The ONE string for "no preferred work chosen" — the mock's copy — on both
@@ -594,7 +602,7 @@
   // is a line item in Needs-attention, never a card). Only what awaits the
   // builder lands here — a "we cover it" note is information, and stays on the
   // full Standing view with the other two, where the banners still render.
-  function renderSystemNotices({ rebaseTasks, need, cost }) {
+  function renderSystemNotices({ rebaseTasks, need, actionNeeds, cost }) {
     const box = document.getElementById('attention-system');
     if (!box) return;
     const rows = [];
@@ -610,13 +618,24 @@
         `<span class="ginbox__line">New claims are paused: ${rebaseTasks.length} confirmed ${one ? 'task' : 'tasks'} can't land yet, so ${one ? 'its' : 'their'} reward is pending. Rebase and re-ship, or release: ${refs}.</span>` +
         `</div></li>`);
     }
-    if (need && need.state === 'action_needed') {
-      const act = need.action && need.action.href
-        ? `<div class="ginbox__actions"><a class="btn-ghost" href="${escapeHtml(need.action.href)}">${escapeHtml(need.action.label || 'Set it up')}</a></div>`
+    // task 1003738: EVERY action_needed need gets its own line, not just the
+    // first. This surface is a list by design (the placement rule in
+    // modules/hall-ui/CLAUDE.md — an action awaiting the builder is a line item
+    // in Needs-attention), but it used to render a single need, so one
+    // permanently-open item suppressed all the others: a builder whose image key
+    // was unset never saw that ideas were sitting before the board undecided.
+    // Ordering still decides which is loudest; it no longer decides which exist.
+    // The `need` fallback keeps a caller that passes only the top need working.
+    const noticeNeeds = (Array.isArray(actionNeeds) && actionNeeds.length)
+      ? actionNeeds
+      : (need && need.state === 'action_needed' ? [need] : []);
+    for (const n of noticeNeeds) {
+      const act = n.action && n.action.href
+        ? `<div class="ginbox__actions"><a class="btn-ghost" href="${escapeHtml(n.action.href)}">${escapeHtml(n.action.label || 'Set it up')}</a></div>`
         : '';
       rows.push(`<li class="ginbox__item ginbox__item--warn"><div class="ginbox__body">` +
-        `<span class="ginbox__kind">${escapeHtml(need.title)}</span>` +
-        `<span class="ginbox__line">${escapeHtml(need.message)}</span>` +
+        `<span class="ginbox__kind">${escapeHtml(n.title)}</span>` +
+        `<span class="ginbox__line">${escapeHtml(n.message)}</span>` +
         `</div>${act}</li>`);
     }
     if (cost && (cost.level === 'warn' || cost.level === 'over')) {

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.623",
+  "version": "1.19.624",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.623",
+      "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.623",
+  "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/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/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.623'; // 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/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);