@bongos/core 1.21.145 → 1.21.146

package/src/bongos/routes/core-update.js

@@ -34,6 +34,7 @@ const { readSoftwareUpdate } = require('../software-update');
 const seams = require('../../module-seams');
 const { loadIdpConfig } = require('../auth-config');
 const upgradeRequest = require('../upgrade-request');
+const { readUpgradeHold } = require('../upgrade-hold');
 
 // WHERE A HOSTED PROJECT'S OWNER TAKES THE UPGRADE (task 1004174, ADR 0339): the hub's
 // own deploy door, scoped to this project — `<hub>/deploy?project=<slug>`. The act stays
@@ -213,6 +214,14 @@ async function readAsk({ update, door, deps }) {
   return upgradeRequest.askState({ ...base, stored });
 }
 
+// A core move this project's own ledger says was rolled back (task 1004730,
+// src/bongos/upgrade-hold.js): which version was tried, why in plain words, and that this
+// project is still on its old version and working. Both reads carry it, the Software update
+// panel and the banner. Fail-soft: a hold that cannot be read is no hold, never a 500.
+async function safeHold(read, args) {
+  try { return (await read(args)) || null; } catch { return null; }
+}
+
 function buildCoreUpdateRouter({
   coreUpdate = readCoreUpdate,
   selfChannel = storedSelfChannel,
@@ -221,6 +230,7 @@ function buildCoreUpdateRouter({
   canUpdate = holdsCorePin,
   doorInputs = () => ({ provisioning: provisioningEnabled(), idp: safeIdpConfig(), hubUpgradeUrl: safeHubUpgradeUrl() }),
   askDeps = defaultAskDeps,
+  upgradeHold = readUpgradeHold,
 } = {}) {
   contributeCoreUpdateToDocket();
   const router = express.Router();
@@ -245,7 +255,8 @@ function buildCoreUpdateRouter({
       // No `deploy_url` any more (task 1004296): the banner on a hall without a door of its
       // own links to Settings → Software update, and the hand-off lives on GET /software-update.
       const { channel, source } = await resolveChannel(selfChannel);
-      res.json({ ok: true, update: { ...(await coreUpdate({ running, channel })), channel_source: source } });
+      const update = await coreUpdate({ running, channel });
+      res.json({ ok: true, update: { ...update, channel_source: source }, held: await safeHold(upgradeHold, { running, offered: update && update.reading === 'ok' ? update.latest : null }) });
     }, { errorCode: 'core_update_failed', message: false }),
   );
 
@@ -283,7 +294,8 @@ function buildCoreUpdateRouter({
       ]);
       const door = updateDoor(doorInputs());
       const ask = await readAsk({ update, door, deps: askDeps() });
-      res.json({ ok: true, update, door, can_update: can === true, ask });
+      const held = await safeHold(upgradeHold, { running, offered: update && update.reading === 'ok' ? update.offered : null });
+      res.json({ ok: true, update, door, can_update: can === true, ask, held });
     }, { errorCode: 'software_update_failed', message: false }),
   );
 

package/src/bongos/upgrade-hold.js

@@ -0,0 +1,96 @@
+'use strict';
+
+// src/bongos/upgrade-hold.js — "we tried that version, it was rolled back, you are fine":
+// what THIS project's own hall says about a core move that failed (task 1004730).
+//
+// WHY. Since task 1004729 the hub moves a hosted project's core on its own, by its update
+// rule, and holds a target that failed so it is not retried every tick. The hub's /deploy
+// page and its blockers said so; the project's OWNER, in their own hall, saw only "Update
+// ready" for a version that had already been tried and undone on their project.
+//
+// NO NEW CHANNEL. The move itself is `bongos upgrade` (scripts/gds/upgrade.js), run with
+// PGDATABASE set to THIS project's database, and its auto-rollback writes one row to this
+// project's own `core_upgrades` ledger: `rolled_back: <why> (attempted A → B, restored A)`.
+// So the fact is already here, in this hall's own database, written by the run that failed.
+// This file reads it back; the hub is never asked and nothing crosses an instance.
+//
+// WHAT IT DOES NOT SEE. A pre-flight that refused, or a move refused before anything
+// changed, wrote nothing here (nothing changed on this project). Those stay on the hub.
+//
+// A HOLD IS SHOWN ONLY WHILE IT IS TRUE:
+//   • the newest ledger row is that rollback (a later move that landed ends it);
+//   • this server runs the version the rollback restored (so "still on it, and working"
+//     is a fact: this answer is being served by it);
+//   • nothing newer than the tried version is offered (a newer release clears the hold —
+//     it may carry the fix, and the hub queues it).
+
+const { compareSemver } = require('../../scripts/gds/update-channel.js');
+const { upgradeReason, classifyFailure } = require('../../scripts/gds/upgrade-outcome.js');
+
+const VERSION_RE = /^\d{1,4}\.\d{1,5}\.\d{1,6}$/;
+// upgrade.js rollback()'s note, exactly: `rolled_back: ${reason} (attempted F → T, restored P)`.
+const ROLLBACK_NOTE_RE = /^rolled_back: (.+) \(attempted \S+ → \S+, restored \S+\)$/;
+
+// What each step that can fail after the pin moved means, for someone who does not run
+// servers. Keyed by upgrade-outcome.js's reason codes; anything else is the general line.
+const REASON_WORDS = Object.freeze({
+  npm_install: 'its files could not be downloaded and installed',
+  integrity_pin: 'its files did not match the ones that were published',
+  migrate: 'the database changes it brings could not be applied to this project',
+  migrate_check_violation: 'the database changes it brings do not fit data this project already has',
+  restart: 'the project did not start on it',
+  health: 'the project did not answer properly after starting on it',
+  disk_full: 'the server ran out of disk space while installing it',
+});
+const GENERAL_WORDS = 'it did not pass its checks';
+
+/**
+ * The hold this project is under, or null. PURE.
+ * @param {object[]} rows      core_upgrades rows, newest first
+ * @param {string}   running   the core this server runs
+ * @param {string?}  offered   the newest release this project's rule offers (null if none/unread)
+ */
+function upgradeHold({ rows, running, offered }) {
+  const last = Array.isArray(rows) ? rows[0] : null;
+  if (!last || typeof last.note !== 'string') return null;
+  const m = ROLLBACK_NOTE_RE.exec(last.note);
+  const tried = String(last.to_version || '');
+  const was = String(last.from_version || '');
+  if (!m || !VERSION_RE.test(tried) || !VERSION_RE.test(was)) return null;
+  if (String(running || '') !== was) return null;
+  if (offered && VERSION_RE.test(String(offered)) && compareSemver(offered, tried) > 0) return null;
+  const reason = upgradeReason({ error: m[1], rolledBack: true });
+  const transient = classifyFailure(reason).class === 'transient';
+  const why = REASON_WORDS[reason] || GENERAL_WORDS;
+  const at = last.applied_at ? new Date(last.applied_at) : null;
+  return {
+    version: tried,
+    still_on: was,
+    reason,
+    retry: transient ? 'later' : 'next_release',
+    at: at && Number.isFinite(at.getTime()) ? at.toISOString() : null,
+    message: `Version ${tried} was tried on this project and did not work: ${why}. `
+      + `It was rolled back automatically, so this project is still on ${was} and working normally. `
+      + (transient
+        ? 'It may be tried again later.'
+        : `${tried} is on hold here, and the next release will be tried when it is out.`),
+  };
+}
+
+/**
+ * Read this project's own ledger and answer upgradeHold. Never throws: a ledger that
+ * cannot be read is "no hold", never a failed Software update panel.
+ */
+async function readUpgradeHold({ running, offered, pool = null } = {}) {
+  try {
+    const db = pool || require('./pool').pool;
+    const { rows } = await db.query(
+      `SELECT from_version, to_version, note, applied_at FROM core_upgrades
+        ORDER BY applied_at DESC, id DESC LIMIT 1`);
+    return upgradeHold({ rows, running, offered });
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { upgradeHold, readUpgradeHold };

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

@@ -13,7 +13,7 @@
 // Run:  node tests/core_auto_upgrade.mjs
 
 import { strict as assert } from 'node:assert';
-import { autoUpgradeTick, AUTO_MOVES_PER_TICK, autoUpgradeEnabled } from '../scripts/gds/provision-auto-upgrade.js';
+import { autoUpgradeTick, AUTO_MOVES_PER_TICK, autoUpgradeEnabled, TRANSIENT_HOLD_MS } from '../scripts/gds/provision-auto-upgrade.js';
 
 let passed = 0;
 let failed = 0;
@@ -32,7 +32,7 @@ function row(over = {}) {
 }
 
 // A fake world: `rows` are candidates, `intents` the provisioning_intents history.
-function makeDeps({ rows = [row()], intents = [], env = {} } = {}) {
+function makeDeps({ rows = [row()], intents = [], env = {}, now } = {}) {
   const queued = [];
   const events = [];
   const db = {
@@ -53,7 +53,7 @@ function makeDeps({ rows = [row()], intents = [], env = {} } = {}) {
     },
     async recordEvent(_db, e) { events.push(e); },
   };
-  return { db, provisioning, env, log: () => {}, queued, events };
+  return { db, provisioning, env, now, log: () => {}, queued, events };
 }
 
 console.log('core auto-upgrade tick (task 1004729)');
@@ -185,5 +185,66 @@ await t('a refusal from enqueueIntent (e.g. the control-plane guard) never fails
   assert.equal(r.queued, 0);
 });
 
+// ---- the hold, by failure class (task 1004730) ------------------------------------------
+// A failure classed `transient` (upgrade-outcome.js: a registry blip, a release still
+// publishing, an install that could not download) already waited out its own 15m/1h/6h
+// backoff inside the intent (intent-retry.js) before it was retired. The automatic path
+// may try that same target once more after TRANSIENT_HOLD_MS; every other class (a known
+// wedge whose fix did not hold, a rule refusing it, an unknown, a failed rollback) stays
+// held until a newer release.
+const T0 = Date.parse('2026-10-14T12:00:00Z');
+const hoursAgo = (h) => new Date(T0 - h * 3600 * 1000).toISOString();
+
+await t('a target retired as TRANSIENT is held for a day, then tried again', async () => {
+  assert.equal(TRANSIENT_HOLD_MS, 24 * 3600 * 1000);
+  const failedAt = (h) => [{ instance_id: 52, action: 'core-upgrade', state: 'error', target_version: '1.21.69', failure_class: 'transient', failure_reason: 'npm_install', updated_at: hoursAgo(h) }];
+  const fresh = makeDeps({ intents: failedAt(2), now: () => T0 });
+  await autoUpgradeTick(fresh);
+  assert.equal(fresh.queued.length, 0, 'held inside the day');
+  const later = makeDeps({ intents: failedAt(25), now: () => T0 });
+  await autoUpgradeTick(later);
+  assert.equal(later.queued.length, 1, 'tried again after the day');
+  assert.equal(later.queued[0].target_version, '1.21.69');
+});
+
+await t('a transient PREFLIGHT error is also released after a day', async () => {
+  const d = makeDeps({ now: () => T0, intents: [{ instance_id: 52, action: 'core-upgrade-preflight', state: 'error', target_version: '1.21.69', failure_class: 'transient', updated_at: hoursAgo(30) }] });
+  await autoUpgradeTick(d);
+  assert.equal(d.queued.length, 1);
+});
+
+await t('every other class stays held however long ago it failed', async () => {
+  for (const cls of ['unknown', 'known_wedge', 'needs_decision', null]) {
+    const d = makeDeps({ now: () => T0, intents: [{ instance_id: 52, action: 'core-upgrade', state: 'error', target_version: '1.21.69', failure_class: cls, updated_at: hoursAgo(24 * 30) }] });
+    await autoUpgradeTick(d);
+    assert.equal(d.queued.length, 0, String(cls));
+  }
+});
+
+await t('a move that finished but left the box behind stays held, whatever its age', async () => {
+  const d = makeDeps({ now: () => T0, rows: [row({ preflight: { target: '1.21.69', ok: true } })],
+    intents: [{ instance_id: 52, action: 'core-upgrade', state: 'done', target_version: '1.21.69', failure_class: null, updated_at: hoursAgo(24 * 30) }] });
+  await autoUpgradeTick(d);
+  assert.equal(d.queued.length, 0);
+});
+
+await t('one held failure of the target wins over an older transient one', async () => {
+  const d = makeDeps({ now: () => T0, intents: [
+    { instance_id: 52, action: 'core-upgrade', state: 'error', target_version: '1.21.69', failure_class: 'transient', updated_at: hoursAgo(72) },
+    { instance_id: 52, action: 'core-upgrade', state: 'error', target_version: '1.21.69', failure_class: 'unknown', updated_at: hoursAgo(48) }] });
+  await autoUpgradeTick(d);
+  assert.equal(d.queued.length, 0);
+});
+
+await t('the intents read carries the failure class and when it failed', async () => {
+  const d = makeDeps();
+  let sql = '';
+  const q = d.db.query;
+  d.db.query = async (s, p) => { if (/FROM provisioning_intents/.test(s)) sql = s; return q(s, p); };
+  await autoUpgradeTick(d);
+  assert.match(sql, /failure_class/);
+  assert.match(sql, /updated_at/);
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 if (failed) process.exit(1);

package/tests/core_upgrade_owner_door.mjs

@@ -344,7 +344,7 @@ const SHELL = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/shell.js')
 // The real shell.js in a DOM stub (the tests/core_update_banner.mjs harness), with the
 // /core-update answer optionally carrying a deploy_url — an older server still sends one —
 // and elements that remember their attributes.
-function boot({ provisioning, deployUrl, pathname = '/settings', hash = '' }) {
+function boot({ provisioning, deployUrl, pathname = '/settings', hash = '', held }) {
   const els = new Map();
   const inserted = [];
   const makeEl = () => ({
@@ -380,7 +380,7 @@ function boot({ provisioning, deployUrl, pathname = '/settings', hash = '' }) {
     BongosClient: {
       createClient: () => ({
         request: (_method, p) => (p === '/api/bongos/core-update'
-          ? Promise.resolve({ status: 200, data: { ok: true, update, deploy_url: deployUrl } })
+          ? Promise.resolve({ status: 200, data: { ok: true, update, deploy_url: deployUrl, held } })
           : new Promise(() => {})),
       }),
     },
@@ -396,6 +396,7 @@ function boot({ provisioning, deployUrl, pathname = '/settings', hash = '' }) {
   windowObj.OTBShell.applyAccess({ authed: true, rank: 'archon', permissions: { 'core.pin.move': true } });
   return {
     banner: () => inserted.find((e) => String(e._html).includes('is available')),
+    notice: () => inserted.find((e) => e.id === 'core-update-notice'),
     deployItem: () => els.get('nav-deploy'),
   };
 }
@@ -449,5 +450,27 @@ await t('on the platform, the local door wins: the banner links /deploy and the
   assert.equal(item.dataset.module, 'provisioning', 'and its module gate, which the platform satisfies');
 });
 
+// Task 1004730: a version this project already tried and rolled back is not announced as
+// "available" with an Upgrade button. The banner says what happened instead, in the owner's
+// words, and points at Software update for the rest.
+await t('a held version: the banner says it was tried and rolled back, and the project is still fine', async () => {
+  const held = { version: '1.19.1033', still_on: '1.19.871', message: 'long form' };
+  const b = boot({ provisioning: false, held });
+  await settle();
+  const n = b.notice();
+  assert.ok(n, 'the banner renders');
+  assert.doesNotMatch(n.innerHTML, /is available/);
+  assert.match(n.innerHTML, /1\.19\.1033<\/strong> was tried on this project and rolled back/);
+  assert.match(n.innerHTML, /still on 1\.19\.871 and working/);
+  assert.match(n.innerHTML, /href="\/settings#software-update">Details</);
+  assert.doesNotMatch(n.innerHTML, />Upgrade</, 'no button to take the version that just failed');
+});
+
+await t('a hold on an OLDER version than the one now out leaves the ordinary banner', async () => {
+  const b = boot({ provisioning: false, held: { version: '1.19.900', still_on: '1.19.871', message: 'x' } });
+  await settle();
+  assert.ok(b.banner(), 'the newer release is announced as usual');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/nav_permission_atoms.mjs

@@ -89,8 +89,9 @@ test('the hall-preview fixture carries every atom /me resolves', () => {
 
 // task 1004685 (the living-city prototype): the held-seat nav and the My agents tab,
 // then the reads it shares with the governor pages (window.__hallReads); task 1004713:
-// the seats read from /me's server-resolved positions block.
-const SHELL_SHA = 'd50a4cc5e6c954b5';
+// the seats read from /me's server-resolved positions block; task 1004730: the banner
+// says a held core version was tried and rolled back.
+const SHELL_SHA = 'b4e4b7ae4fea6bc1';
 
 test('shell.js has not changed without its cache-bust being bumped', () => {
   const actual = crypto.createHash('sha256').update(SHELL).digest('hex').slice(0, 16);

package/tests/upgrade_hold.mjs

@@ -0,0 +1,207 @@
+// tests/upgrade_hold.mjs — a failed core move is told to the project's OWN owner, in their
+// own hall (task 1004730).
+//
+// The move is `bongos upgrade` run against THIS project's database; its auto-rollback
+// writes `rolled_back: <why> (attempted A → B, restored A)` to this project's own
+// core_upgrades ledger. src/bongos/upgrade-hold.js reads that row back, and GET
+// /software-update (Settings → Software update) and GET /core-update (the banner) carry
+// it as `held`: which version was tried, that it was rolled back, and that the project is
+// still on its old version and working. A newer release clears it.
+//
+// Run:  node tests/upgrade_hold.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { upgradeHold, readUpgradeHold } = require('../src/bongos/upgrade-hold.js');
+
+let passed = 0;
+let failed = 0;
+const t = async (name, fn) => {
+  try { await fn(); passed += 1; console.log(`  PASS  ${name}`); }
+  catch (e) { failed += 1; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+// The row upgrade.js rollback() writes, byte for byte in its note.
+const rollbackRow = (why = 'migrate failed', from = '1.21.20', to = '1.21.115') => ({
+  from_version: from, to_version: to, applied_at: '2026-10-14T09:00:00.000Z',
+  note: `rolled_back: ${why} (attempted ${from} → ${to}, restored ${from})`,
+});
+const okRow = { from_version: '1.21.20', to_version: '1.21.69', applied_at: '2026-10-15T09:00:00.000Z', note: null };
+
+console.log('upgrade hold, read by the project itself (task 1004730)');
+
+await t('a rolled-back move is held, in plain words: tried, rolled back, still on the old one and working', () => {
+  const h = upgradeHold({ rows: [rollbackRow()], running: '1.21.20', offered: '1.21.115' });
+  assert.equal(h.version, '1.21.115');
+  assert.equal(h.still_on, '1.21.20');
+  assert.equal(h.reason, 'migrate');
+  assert.equal(h.retry, 'next_release');
+  assert.equal(h.at, '2026-10-14T09:00:00.000Z');
+  assert.match(h.message, /Version 1\.21\.115 was tried on this project/);
+  assert.match(h.message, /rolled back/);
+  assert.match(h.message, /still on 1\.21\.20 and working/);
+  assert.match(h.message, /database changes/, 'the reason, in words an owner reads');
+  assert.doesNotMatch(h.message, /[—–]/, 'voice rule: no dashes in copy');
+});
+
+await t('each step that can fail reads as its own plain reason; an unknown one as the general line', () => {
+  const cases = [['npm install failed', 'npm_install', /downloaded and installed/, 'later'],
+    ['restart failed', 'restart', /did not start/, 'next_release'],
+    ['health check failed after restart', 'health', /did not answer properly/, 'next_release'],
+    ['served core version did not change (still 1.21.20, expected 1.21.115)', 'health', /did not answer properly/, 'next_release'],
+    ['integrity pin mismatch', 'integrity_pin', /did not match/, 'next_release'],
+    ['something nobody wrote down', 'unknown', /did not pass its checks/, 'next_release']];
+  for (const [why, reason, words, retry] of cases) {
+    const h = upgradeHold({ rows: [rollbackRow(why)], running: '1.21.20', offered: '1.21.115' });
+    assert.equal(h.reason, reason, why);
+    assert.match(h.message, words, why);
+    assert.equal(h.retry, retry, why);
+  }
+  assert.match(upgradeHold({ rows: [rollbackRow('npm install failed')], running: '1.21.20', offered: null }).message, /may be tried again later/);
+});
+
+await t('a newer release clears the hold: it may carry the fix', () => {
+  assert.equal(upgradeHold({ rows: [rollbackRow()], running: '1.21.20', offered: '1.21.116' }), null);
+});
+
+await t('the hold stands when nothing, or nothing newer, is offered', () => {
+  assert.ok(upgradeHold({ rows: [rollbackRow()], running: '1.21.20', offered: null }));
+  assert.ok(upgradeHold({ rows: [rollbackRow()], running: '1.21.20', offered: '1.21.100' }));
+});
+
+await t('a later move that landed ends it (only the newest ledger row counts)', () => {
+  assert.equal(upgradeHold({ rows: [okRow, rollbackRow()], running: '1.21.69', offered: null }), null);
+});
+
+await t('"still on it and working" is said only by the version the rollback restored', () => {
+  assert.equal(upgradeHold({ rows: [rollbackRow()], running: '1.21.30', offered: null }), null);
+  assert.equal(upgradeHold({ rows: [rollbackRow()], running: null, offered: null }), null);
+});
+
+await t('rows this file did not write are no hold', () => {
+  for (const rows of [[], null, [okRow], [{ ...rollbackRow(), note: 'rolled_back: whatever' }], [{ ...rollbackRow(), to_version: 'x' }]]) {
+    assert.equal(upgradeHold({ rows, running: '1.21.20', offered: null }), null, JSON.stringify(rows));
+  }
+});
+
+await t('readUpgradeHold reads the newest ledger row, and a failed read is no hold, never a throw', async () => {
+  let sql = '';
+  const pool = { query: async (s) => { sql = s; return { rows: [rollbackRow()] }; } };
+  const h = await readUpgradeHold({ running: '1.21.20', offered: '1.21.115', pool });
+  assert.equal(h.version, '1.21.115');
+  assert.match(sql, /FROM core_upgrades/);
+  assert.match(sql, /ORDER BY applied_at DESC/);
+  assert.equal(await readUpgradeHold({ running: '1.21.20', pool: { query: async () => { throw new Error('no table'); } } }), null);
+});
+
+// ---- the two reads the hall makes ----------------------------------------------------
+
+async function drive(p, deps) {
+  const auth = require('../src/bongos/auth.js');
+  const saved = { b: auth.requireBuilder, p: auth.requirePermission };
+  auth.requireBuilder = (req, _res, next) => { req.builder = { id: '7' }; next(); };
+  auth.requirePermission = () => (_req, _res, next) => next();
+  const build = require('../src/bongos/routes/core-update.js');
+  const express = require('express');
+  const app = express();
+  try {
+    app.use(build({ askDeps: () => ({ hub: null, getSetting: async () => null }), canUpdate: async () => true,
+      doorInputs: () => ({ provisioning: false, idp: null, hubUpgradeUrl: 'https://cloudbongos.com/deploy?project=toast' }), ...deps }));
+  } finally { auth.requireBuilder = saved.b; auth.requirePermission = saved.p; }
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  try {
+    const res = await fetch(`http://127.0.0.1:${server.address().port}${p}`);
+    return { status: res.status, body: await res.json() };
+  } finally { server.close(); }
+}
+const ledger = { query: async () => ({ rows: [rollbackRow()] }) };
+const realHold = (a) => readUpgradeHold({ ...a, pool: ledger });
+
+await t('GET /software-update carries the hold and its plain reason (Settings → Software update)', async () => {
+  let asked = null;
+  const r = await drive('/software-update', {
+    softwareUpdate: async ({ running }) => ({ reading: 'ok', running, offered: '1.21.115' }),
+    upgradeHold: (a) => { asked = a; return realHold({ ...a, running: '1.21.20' }); },
+  });
+  assert.equal(r.status, 200);
+  assert.equal(asked.offered, '1.21.115', 'the hold is judged against what this project is offered');
+  assert.equal(r.body.held.version, '1.21.115');
+  assert.match(r.body.held.message, /still on 1\.21\.20 and working/);
+});
+
+await t('GET /software-update: a newer offer means no hold, and an unread registry still shows it', async () => {
+  const newer = await drive('/software-update', { softwareUpdate: async () => ({ reading: 'ok', offered: '1.21.116' }),
+    upgradeHold: (a) => realHold({ ...a, running: '1.21.20' }) });
+  assert.equal(newer.body.held, null);
+  const unread = await drive('/software-update', { softwareUpdate: async () => ({ reading: 'no_answer', offered: null }),
+    upgradeHold: (a) => realHold({ ...a, running: '1.21.20' }) });
+  assert.equal(unread.body.held.version, '1.21.115');
+});
+
+await t('GET /core-update carries it too, for the banner', async () => {
+  const r = await drive('/core-update', {
+    coreUpdate: async () => ({ reading: 'ok', running: '1.21.20', latest: '1.21.115', behind: true }),
+    selfChannel: async () => null,
+    upgradeHold: (a) => realHold({ ...a, running: '1.21.20' }),
+  });
+  assert.equal(r.status, 200);
+  assert.equal(r.body.held.version, '1.21.115');
+});
+
+await t('a hold read that throws never fails either read', async () => {
+  const boom = async () => { throw new Error('boom'); };
+  const a = await drive('/software-update', { softwareUpdate: async () => ({ reading: 'ok', offered: null }), upgradeHold: boom });
+  assert.equal(a.status, 200);
+  assert.equal(a.body.held, null);
+  const b = await drive('/core-update', { coreUpdate: async () => ({ reading: 'ok', behind: false }), selfChannel: async () => null, upgradeHold: boom });
+  assert.equal(b.status, 200);
+  assert.equal(b.body.held, null);
+});
+
+// ---- the Software update panel draws it ----------------------------------------------
+
+const PANEL_SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings-software-update.js'), 'utf8');
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+async function panel(data) {
+  const el = () => ({ hidden: true, textContent: '', _html: '', dataset: {}, set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; }, querySelectorAll: () => [] });
+  const els = new Map([['software-update-scroll', el()], ['su-body', el()], ['su-note', el()], ['settings-groups', el()]]);
+  els.get('settings-groups').dataset.active = 'update';
+  const windowObj = {
+    BongosClient: { createClient: () => ({ request: async () => ({ ok: true, status: 200, data }) }) },
+    OTB: { escapeHtml }, location: { assign() {} },
+  };
+  const sandbox = { window: windowObj, document: { getElementById: (id) => els.get(id) || null, addEventListener() {} }, console, setTimeout, Date, Math, URL, Promise, String, Number };
+  vm.createContext(sandbox);
+  vm.runInContext(PANEL_SRC, sandbox, { filename: 'settings-software-update.js' });
+  for (let i = 0; i < 10; i++) await new Promise((r) => setTimeout(r, 0));
+  return els.get('su-body').innerHTML;
+}
+
+await t('the panel says it in the owner\'s words, and does not offer the held version as "Update ready"', async () => {
+  const held = upgradeHold({ rows: [rollbackRow()], running: '1.21.20', offered: '1.21.115' });
+  const html = await panel({ ok: true, update: { reading: 'ok', running: '1.21.20', offered: '1.21.115', whats_new: null },
+    door: { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=toast' }, can_update: true, ask: {}, held });
+  assert.ok(html.includes(escapeHtml(held.message)), 'the plain message is drawn');
+  assert.match(html, /On hold/);
+  assert.doesNotMatch(html, /Update ready/);
+  assert.doesNotMatch(html, /id="su-update"/, 'no button to take the version that just failed');
+});
+
+await t('no hold, no change: the panel draws exactly what it did before', async () => {
+  const data = { ok: true, update: { reading: 'ok', running: '1.21.20', offered: '1.21.116', whats_new: null }, door: { kind: 'cli', url: null }, can_update: true, ask: {} };
+  const html = await panel({ ...data, held: null });
+  assert.match(html, /Update ready/);
+  assert.equal(html, await panel(data));
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);