@bongos/core 1.21.70 → 1.21.72

package/scripts/gds/start.js

@@ -615,7 +615,7 @@ function instanceNotRunningCard({ origin, depsMissing } = {}) {
     out.push(`2. If that doesn't load either, the instance itself is down: \`curl -sI ${origin}/healthz\` says whether it's answering.`);
     out.push(`3. Once it answers, re-run ${surface.code(surface.action('start'))}.`);
     out.push('');
-    out.push(`${surface.strong(`Don't run ${surface.code('bongos dev')} for this.`)} It stands up a separate local instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
+    out.push(`${surface.strong(`Don't run ${surface.code(surface.cli('dev'))} for this.`)} It stands up a separate local instance with its own empty database — it cannot show you this board, and it would hide the outage behind an empty one.`);
     if (depsMissing) {
       out.push('');
       out.push(`(The ${surface.code('bongos')} CLI isn't installed here. It's optional — the website above is the same board. ${surface.code('@bongos/core')} is ${surface.strong('public')} on npm, so ${surface.code('npm install @bongos/core')} needs no token or login; a failure here is a real error, not the expected tokenless 404 it used to be.)`);
@@ -629,10 +629,10 @@ function instanceNotRunningCard({ origin, depsMissing } = {}) {
   if (depsMissing) {
     out.push(`${n++}. \`npm install\` — installs the toolchain first (the \`bongos\` CLI ships inside \`@bongos/core\`, so nothing else runs until this does).`);
   }
-  out.push(`${n++}. \`bongos dev\` — one command: starts Postgres, builds the tables, runs the server, and signs you in.`);
+  out.push(`${n++}. ${surface.code(surface.cli('dev'))} — one command: starts Postgres, builds the tables, runs the server, and signs you in.`);
   out.push(`${n++}. Re-run ${surface.code(surface.action('start'))}.`);
   out.push('');
-  out.push(`Meant to work on a *different* instance that's already running? Sign in to it with \`bongos login <url>\` first.`);
+  out.push(`Meant to work on a *different* instance that's already running? Sign in to it with ${surface.code(surface.cli('login <url>'))} first.`);
   return out.join('\n');
 }
 function emitInstanceNotRunningCard(opts) {
@@ -980,7 +980,7 @@ async function main() {
 
   // ---------- next ----------
   console.log('');
-  console.log(`→ ${surface.isTerminal() ? `Claim one with ${surface.code('bongos claim <id>')} in a checkout` : `${surface.strong('Tell me a number')} to claim it`}.`);
+  console.log(`→ ${surface.isTerminal() ? `Claim one with ${surface.code(surface.cli('claim <id>'))} in a checkout` : `${surface.strong('Tell me a number')} to claim it`}.`);
   if (full) {
     console.log('');
     console.log('Commands:');

package/scripts/gds/surface.js

@@ -43,11 +43,23 @@ function taskRef(id, url, env = process.env) {
   return isTerminal(env) ? `#${id}` : `[#${id}](${url}${id})`;
 }
 
+// How a reader runs the CLI (task 1004621). The `bongos` bin ships inside @bongos/core and is not
+// on PATH — in a project it sits at node_modules/.bin/bongos, and the global @cloudbongos/cli that
+// once put a bare `bongos` on PATH is retired (ADR 0324). `npx` finds the local bin with no setup,
+// in a project and in a core checkout alike, so every printed command uses it. A bare `bongos …`
+// sent the first command of a project's session into `command not found`.
+const CLI = 'npx bongos';
+
+// A CLI command line to print: `cli('claim <id>')` → `npx bongos claim <id>`.
+function cli(rest) {
+  return rest ? `${CLI} ${rest}` : CLI;
+}
+
 // An action the reader can actually run. In a session that is the slash command; in a terminal it
-// is the `bongos` verb. `/builder-ship 123` does not exist outside Claude Code.
+// is the `npx bongos` verb. `/builder-ship 123` does not exist outside Claude Code.
 function action(verb, arg, env = process.env) {
   const tail = arg == null ? '' : ` ${arg}`;
-  return isTerminal(env) ? `bongos ${verb}${tail}` : `/builder-${verb}${tail}`;
+  return isTerminal(env) ? cli(`${verb}${tail}`) : `/builder-${verb}${tail}`;
 }
 
 // Markdown emphasis is decoration in a feed and literal asterisks on a console.
@@ -86,4 +98,4 @@ function table(headers, rows, env = process.env) {
   ].join('\n');
 }
 
-module.exports = { AGENT, TERMINAL, resolveSurface, isTerminal, taskRef, action, strong, em, code, table };
+module.exports = { AGENT, TERMINAL, CLI, cli, resolveSurface, isTerminal, taskRef, action, strong, em, code, table };

package/scripts/gds/task.js

@@ -19,10 +19,12 @@
 // Task CREATION is Archon-gated SERVER-SIDE (creating work shapes scope, ADR 0016). This
 // CLI adds no authority — a lower rank gets a clear 403 message pointing at idea capture.
 
-const { cliClient, requireSession, arg, hasFlag } = require('./cli-lib');
+const { cliClient, requireSession, arg, hasFlag, errCode } = require('./cli-lib');
 // task 1003109: the ship-time VISUAL. The CLI screens the file with the SERVER's
 // own constants, so what it accepts is exactly what the upload route accepts.
 const taskVisuals = require('../../modules/lifecycle/task-visuals');
+// task 1004597: the one spelling of "this is platform upkeep" (kind infra, no goal).
+const { UPKEEP_KIND } = require('../../modules/lifecycle/upkeep-home');
 
 // Valid enums (mirrors the server's task-classifier vocab; a friendly client-side check
 // so an obvious typo fails before the round-trip — the server stays authoritative).
@@ -87,6 +89,8 @@ function usage() {
   console.error('  bongos task visual <id> <image> [--alt "caption"]   attach or replace the ship-time visual');
   console.error('  bongos task visual <id> --remove                    remove it again');
   console.error('  bongos task visual <id> <image> --slot <name>       attach or replace a named visual (e.g. after-phone-dark)');
+  console.error('\n  Platform upkeep (a Bongos upgrade, maintenance) needs no goal: pass --kind infra');
+  console.error("  and leave out --goal, and it is filed under the version's maintenance goal.");
   console.error(`\n  kinds: ${VALID_KINDS.join(' | ')}`);
   console.error(`  disciplines: ${VALID_DISCIPLINES.join(' | ')}`);
 }
@@ -111,6 +115,22 @@ async function resolveDefaultVersion(api) {
   return building[0].id;
 }
 
+// goalRequiredHelp — PURE: what a builder reads when a task names no goal
+// (task 1004597). Two ways forward: name a product goal, or — when the work is
+// platform upkeep such as a Bongos upgrade — file it as kind infra with no goal.
+function goalRequiredHelp(body) {
+  const lines = ['Every task belongs to a goal, and this one did not name one.'];
+  if (body && body.kind === UPKEEP_KIND) {
+    lines.push(`Version ${body.version_id} is not being built right now, so it has no maintenance goal.`);
+    lines.push('Re-run with --version <the version being built> (see `bongos status`).');
+  } else {
+    lines.push('  - Product work: re-run with --goal <id> (`bongos status` lists the goals).');
+    lines.push('  - Platform upkeep (a Bongos upgrade or other maintenance): re-run with --kind infra and no --goal.');
+    lines.push("    It goes into this version's maintenance goal.");
+  }
+  return lines.join('\n');
+}
+
 async function cmdNew(args) {
   const { body, errors } = buildTaskBody(args);
   if (errors.length) { console.error('task new: ' + errors.join('; ') + '\n'); usage(); process.exit(2); }
@@ -120,7 +140,7 @@ async function cmdNew(args) {
   if (!body.version_id) {
     body.version_id = await resolveDefaultVersion(api);
     if (!body.version_id) {
-      console.error('task new: could not resolve an active version — pass --version <id> (see `bongos status`).');
+      console.error('task new: could not resolve an active version — pass --version <id> (see `npx bongos status`).');
       process.exit(2);
     }
   }
@@ -128,7 +148,13 @@ async function cmdNew(args) {
   if (r.status === 403) {
     console.error('Creating a task is Archon-gated (creating work shapes scope). Your rank is lower, so the server declined.');
     console.error('To propose it instead, capture an idea for triage:');
-    console.error('  bongos exec scripts/gds/capture.js "<your idea>"');
+    console.error('  npx bongos exec scripts/gds/capture.js "<your idea>"');
+    process.exit(1);
+  }
+  // task 1004597: a goal-less filing is refused unless it is platform upkeep.
+  // Say both ways forward in plain words instead of dumping the raw error.
+  if (r.status === 400 && errCode(r.data) === 'goal_id_required') {
+    console.error(goalRequiredHelp(body));
     process.exit(1);
   }
   if (r.status !== 201 || !r.data?.task) {
@@ -141,8 +167,9 @@ async function cmdNew(args) {
   console.log(`✓ Created task #${task.id} [${task.status}] — ${task.title}`);
   console.log(`  kind=${task.kind} · discipline=${task.discipline}${task.priority ? ` · P${task.priority}` : ''}${task.goal_id ? ` · goal ${task.goal_id}` : ''}`);
   console.log(`  ${hallLink(API_BASE, task.id)}`);
+  if (r.data.goal_home === 'maintenance') console.log(`  Filed under ${body.version_id}'s maintenance goal, the standing home for platform upkeep.`);
   if (task.status !== 'ready') console.log(`  (status '${task.status}' — pass --ready to make it claimable now, deps permitting)`);
-  console.log(`  next: bongos claim ${task.id}`);
+  console.log(`  next: npx bongos claim ${task.id}`);
 }
 
 async function cmdShow(args) {
@@ -243,4 +270,4 @@ if (require.main === module) {
   main().catch((err) => { console.error('fatal:', err); process.exit(1); });
 }
 
-module.exports = { buildTaskBody, VALID_KINDS, VALID_DISCIPLINES, csv, hallLink };
+module.exports = { buildTaskBody, goalRequiredHelp, VALID_KINDS, VALID_DISCIPLINES, csv, hallLink };

package/scripts/gds/upgrade-operator.js

@@ -0,0 +1,73 @@
+// scripts/gds/upgrade-operator.js — "who upgrades this project?" for `bongos upgrade`
+// run from a builder's own computer (task 1004596).
+//
+// A hosted project (its Settings → Software update button leads to the hub — door kind
+// 'hub', see src/bongos/routes/core-update.js updateDoor) lives on its operator's server.
+// Its builders work from a laptop checkout that has no database and no server access. Run
+// there, `bongos upgrade` used to say only "cannot determine which database to migrate.
+// Set PGDATABASE…" — and an assistant reading that, plus the release recipe, wrote the
+// builder server steps full of guessed names for a machine they cannot reach. This module
+// replaces that dead end with the one supported path: the operator upgrades it, and here
+// is how to ask.
+//
+// THE CONDITION, and why it cannot touch the real operator path: BOTH must hold —
+//   1. no database is known in this checkout (no PGDATABASE, no db.database in the
+//      branding pack). On the server a database is always known, or upgrade.js already
+//      refuses there; so the server never reaches step 2.
+//   2. the project, asked through this builder's own CLI session, says its update door is
+//      the hub's. No session, no answer, an older core, a self-hosted or provisioning
+//      instance → no message, and upgrade.js behaves exactly as before.
+
+// Ask the project (via this builder's CLI session) where its Update button leads.
+// Returns { kind, url, hall } or null on ANY failure — a missing answer is never a verdict.
+async function readUpdateDoor({ timeoutMs = 5000 } = {}) {
+  try {
+    const { readSessionToken, dispatchedFetch, noKeepAliveDispatcher, CLI_USER_AGENT, hallBase } = require('./cli-lib');
+    const session = readSessionToken();
+    if (!session) return null;
+    const res = await dispatchedFetch(`${session.apiBase}/api/bongos/software-update`, {
+      headers: { Authorization: `Bearer ${session.token}`, 'User-Agent': CLI_USER_AGENT },
+      signal: AbortSignal.timeout(timeoutMs),
+      dispatcher: noKeepAliveDispatcher(),
+    });
+    if (!res.ok) return null;
+    const body = await res.json();
+    const door = body && body.door;
+    if (!door || typeof door.kind !== 'string') return null;
+    return { kind: door.kind, url: door.url || null, hall: hallBase(session.apiBase) };
+  } catch { return null; }
+}
+
+// The door when the operator runs this project and this checkout is not where it runs;
+// null otherwise (including whenever the answer cannot be read).
+async function operatorRunsThisProject({ instanceDir }, deps = {}) {
+  const { db } = (deps.resolveInstanceDb || require('./upgrade').resolveInstanceDb)({ instanceDir }, deps.run);
+  if (db) return null;
+  const door = await (deps.readUpdateDoor || readUpdateDoor)();
+  return door && door.kind === 'hub' ? door : null;
+}
+
+// What the builder (and any assistant reading over their shoulder) is told. Plain words,
+// one supported path, no server steps and nothing for anyone to fill in.
+function operatorRunMessage(door = {}) {
+  const settings = door.hall ? `${door.hall}/settings#software-update` : 'Settings → Software update';
+  return [
+    'This project is upgraded by its operator, not from this computer.',
+    'It runs on the operator\'s server, and nothing you run here can upgrade it.',
+    '',
+    'To ask for the upgrade:',
+    `  • Open ${settings} and use the button there.`,
+    '  • Or, from this terminal:  bongos feedback "Please upgrade this project to the latest version"',
+    '',
+    'There are no server steps for you to take. An assistant should not write any, or guess',
+    'server, database or service names for this project — pass the request on instead.',
+  ].join('\n') + '\n';
+}
+
+// The message to show, or null — what `bongos upgrade` (upgrade.js main) asks before anything else.
+async function operatorNotice({ instanceDir }, deps = {}) {
+  const door = await operatorRunsThisProject({ instanceDir }, deps);
+  return door ? operatorRunMessage(door) : null;
+}
+
+module.exports = { readUpdateDoor, operatorRunsThisProject, operatorRunMessage, operatorNotice };

package/scripts/gds/upgrade.js

@@ -1433,7 +1433,7 @@ function parseArgs(argv) {
   };
 }
 
-async function main(argv = process.argv.slice(2)) {
+async function main(argv = process.argv.slice(2), deps = {}) {
   if (hasFlag('--help', argv) || argv[0] === 'help') {
     process.stdout.write([
       'bongos upgrade — pull the Cloud Bongos core to a new version and apply it.',
@@ -1471,9 +1471,14 @@ async function main(argv = process.argv.slice(2)) {
   }
   // Backward-compatible: bare `bongos upgrade` (no --to) is the documented module-compatibility
   // PRE-CHECK — unchanged behavior, delegated to the module CLI. A --to switches to the real channel.
+  // task 1004596: from a builder's own checkout of a project its OPERATOR runs, say who upgrades it and how to ask — never a server-only refusal (upgrade-operator.js has the condition).
+  const operatorMsg = await (deps.operatorNotice || require('./upgrade-operator').operatorNotice)({ instanceDir: path.resolve(arg('--instance', argv) || process.cwd()) });
   if (!arg('--to', argv)) {
-    return require('./module').cmdUpgrade(argv);
+    const code = await (deps.cmdUpgrade || require('./module').cmdUpgrade)(argv);
+    if (operatorMsg) process.stdout.write(`\n${operatorMsg}`);
+    return code;
   }
+  if (operatorMsg) { process.stderr.write(`\n✖ ${operatorMsg}`); return 1; }
   const res = await runUpgrade(parseArgs(argv));
   if (!res.ok) { process.stderr.write(`\n✖ ${res.error || 'upgrade failed'}\n${require('./upgrade-outcome').outcomeLine(res)}`); return 1; } // the outcome line: how far it got, for the deploy runner (task 1004446)
   return 0;

package/scripts/hall-preview/server.js

@@ -180,6 +180,9 @@ const CANNED_WRITES = [
   // a vote cast from the street's matter card (task 1004528), so the card's
   // answer (the toast, the building lighting) renders here too.
   ['POST', /^government\/board\/items\/\d+\/votes$/, 'government__board__items__votes.post'],
+  // Settings → Software update's "Ask for this upgrade" (task 1004595), so the
+  // pending line the panel draws after the press renders here too.
+  ['POST', /^software-update\/request$/, 'software-update__request.post'],
 ];
 
 // A DATE THAT ROTS CANNOT DEMO AN AGE SIGNAL (task 1004041). The help-request

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

@@ -33,6 +33,7 @@ const { readCoreUpdate, readCoreUpgrades } = require('../core-update');
 const { readSoftwareUpdate } = require('../software-update');
 const seams = require('../../module-seams');
 const { loadIdpConfig } = require('../auth-config');
+const upgradeRequest = require('../upgrade-request');
 
 // 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
@@ -73,12 +74,22 @@ function hubManageLinks(config) {
 //   local — this hall runs the door: its own /deploy.
 //   hub   — a hosted project: the hub's door for this project (ADR 0339 D3).
 //   cli   — neither: a self-hosted instance, upgraded on its server with `bongos upgrade`.
-function updateDoor({ provisioning, idp }) {
+// A hosted project that does not federate its sign-in (a cloud-host, or one keeping its own
+// GitHub app) has no idp config to derive the hub from, so provisioning writes the door's
+// address as <PREFIX>_HUB_UPGRADE_URL (task 1004608). Without it, those owners were told to
+// run `bongos upgrade` on a server the platform runs. Only the hub's /deploy path is taken.
+const HUB_UPGRADE_URL_RE = /^https?:\/\/[^\s"'<>/]+\/deploy\?project=[A-Za-z0-9._%-]+$/;
+function updateDoor({ provisioning, idp, hubUpgradeUrl }) {
   if (provisioning) return { kind: 'local', url: '/deploy' };
-  const url = hubDeployUrl(idp);
+  const url = hubDeployUrl(idp)
+    || (typeof hubUpgradeUrl === 'string' && HUB_UPGRADE_URL_RE.test(hubUpgradeUrl.trim()) ? hubUpgradeUrl.trim() : null);
   return url ? { kind: 'hub', url } : { kind: 'cli', url: null };
 }
 
+function safeHubUpgradeUrl() {
+  try { return require('../../instance-config').resolveEnv('HUB_UPGRADE_URL') || null; } catch { return null; }
+}
+
 function provisioningEnabled() {
   try { return require('../../modules').isModuleEnabled('provisioning'); } catch { return false; }
 }
@@ -164,16 +175,57 @@ async function resolveChannel(selfChannel) {
   return { channel, source: channel ? 'deploy' : 'default' };
 }
 
+// "Ask for this upgrade" (task 1004595): what src/bongos/upgrade-request.js needs from
+// the outside world, resolved per request so a test can stand every piece in. The receipt
+// goes into the SAME store the public redeem route reads (routes/feedback.js).
+function defaultAskDeps() {
+  const ps = require('../project-settings');
+  const fb = require('./feedback');
+  return {
+    hub: fb.feedbackHub(),
+    host: configuredHost(),
+    getSetting: ps.getSetting,
+    setSetting: ps.setSetting,
+    issueReceipt: (r) => fb.defaultReceiptStore().issue(r),
+  };
+}
+
+// The host this project answers on, from its OWN branding pack (domains is server-only):
+// the origin the hub calls back to redeem the receipt. Never read from the request: a
+// Host or X-Forwarded-Host header is the caller's to write, and would let them point the
+// hub's call-back at any address they like. '' when the pack names none.
+function configuredHost() {
+  try {
+    const d = require('../../branding').branding().domains || {};
+    return new URL(d.publicOrigin || d.buildersOrigin).host;
+  } catch { return ''; }
+}
+
+// The page's ask state. Fail-soft: a stored row that cannot be read is "not asked yet",
+// never a 500 on the whole Software update panel.
+async function readAsk({ update, door, deps }) {
+  const offered = update && update.reading === 'ok' ? update.offered : null;
+  const base = { offered, host: upgradeRequest.projectHost(deps.host), doorKind: door.kind, hub: deps.hub };
+  let stored = null;
+  if (offered && upgradeRequest.isOperatorRun(base)) {
+    try { stored = upgradeRequest.parseStored(await deps.getSetting(upgradeRequest.SETTING_KEY)); } catch { stored = null; }
+  }
+  return upgradeRequest.askState({ ...base, stored });
+}
+
 function buildCoreUpdateRouter({
   coreUpdate = readCoreUpdate,
   selfChannel = storedSelfChannel,
   upgrades = readCoreUpgrades,
   softwareUpdate = readSoftwareUpdate,
   canUpdate = holdsCorePin,
-  doorInputs = () => ({ provisioning: provisioningEnabled(), idp: safeIdpConfig() }),
+  doorInputs = () => ({ provisioning: provisioningEnabled(), idp: safeIdpConfig(), hubUpgradeUrl: safeHubUpgradeUrl() }),
+  askDeps = defaultAskDeps,
 } = {}) {
   contributeCoreUpdateToDocket();
   const router = express.Router();
+  // One send at a time: a double press waits for the first and is answered from its row.
+  let asking = null;
 
   router.get(
     '/core-update',
@@ -229,10 +281,51 @@ function buildCoreUpdateRouter({
         resolveChannel(selfChannel).then(async ({ channel, source }) => ({ ...(await softwareUpdate({ running, channel })), channel_source: source })),
         canUpdate(req),
       ]);
-      res.json({ ok: true, update, door: updateDoor(doorInputs()), can_update: can === true });
+      const door = updateDoor(doorInputs());
+      const ask = await readAsk({ update, door, deps: askDeps() });
+      res.json({ ok: true, update, door, can_update: can === true, ask });
     }, { errorCode: 'software_update_failed', message: false }),
   );
 
+  // POST /software-update/request — "Ask for this upgrade" (task 1004595). On a project
+  // the hub's operator runs, sends one request for the version this project is offered
+  // to the operator, through the direct feedback door, and remembers it so the page can
+  // say it is pending. The version is the server's own reading, never the caller's.
+  // Idempotent per version; a different version waits out a 24h cooldown (429).
+  // rank: core.pin.move — the same atom as the Update button the panel draws.
+  router.post(
+    '/software-update/request',
+    auth.requireBuilder,
+    auth.requirePermission('core.pin.move'),
+    asyncHandler('POST /software-update/request', async (req, res) => {
+      while (asking) { try { await asking; } catch { /* the next one tries for itself */ } }
+      const run = (async () => {
+        let running = null;
+        try { running = require('../../module-api').CORE_VERSION; } catch { /* version unknown */ }
+        const { channel } = await resolveChannel(selfChannel);
+        const update = await softwareUpdate({ running, channel });
+        const door = updateDoor(doorInputs());
+        const deps = askDeps();
+        return upgradeRequest.requestUpgrade({
+          host: deps.host,
+          running,
+          wanted: update && update.reading === 'ok' ? update.offered : null,
+          builder: req.builder,
+          doorKind: door.kind,
+        }, deps);
+      })();
+      asking = run;
+      let out;
+      try { out = await run; } finally { if (asking === run) asking = null; }
+      if (out.status >= 400) {
+        const { error, message, ...details } = out.body;
+        if (details.retry_after_seconds) res.set('Retry-After', String(details.retry_after_seconds));
+        return res.fail(error, { status: out.status, message, details });
+      }
+      res.status(out.status).json(out.body);
+    }, { errorCode: 'upgrade_request_failed', message: false }),
+  );
+
   // GET /project/manage-link — the hub's page for THIS project, where its owner takes it
   // offline or disconnects it (task 1004570). On a hosted project the owner is its Archon,
   // so the read is Archon-only: a builder below that is refused and the hall draws no
@@ -254,4 +347,5 @@ function buildCoreUpdateRouter({
 module.exports = buildCoreUpdateRouter;
 module.exports.hubManageLinks = hubManageLinks;
 module.exports.hubDeployUrl = hubDeployUrl;
+module.exports.updateDoor = updateDoor;
 module.exports.coreUpdateDocketMatters = coreUpdateDocketMatters;

package/src/bongos/routes/feedback.js

@@ -77,7 +77,16 @@ function makeReceiptStore({ now = Date.now, ttlMs = RECEIPT_TTL_MS, max = RECEIP
   };
 }
 
-function buildFeedbackRouter({ store = makeReceiptStore(), hub = feedbackHub } = {}) {
+// The process's one receipt store. Shared, because a receipt is redeemed at the public
+// route below whoever issued it: the CLI's POST /feedback/receipt, or this project's own
+// "Ask for this upgrade" (src/bongos/upgrade-request.js, task 1004595).
+let sharedStore = null;
+function defaultReceiptStore() {
+  if (!sharedStore) sharedStore = makeReceiptStore();
+  return sharedStore;
+}
+
+function buildFeedbackRouter({ store = defaultReceiptStore(), hub = feedbackHub } = {}) {
   const router = express.Router();
 
   // rank: any signed-in builder — a receipt only says "this builder sent this
@@ -120,5 +129,6 @@ function buildFeedbackRouter({ store = makeReceiptStore(), hub = feedbackHub } =
 
 module.exports = buildFeedbackRouter;
 module.exports.makeReceiptStore = makeReceiptStore;
+module.exports.defaultReceiptStore = defaultReceiptStore;
 module.exports.feedbackHub = feedbackHub;
 module.exports.DEFAULT_FEEDBACK_HUB = DEFAULT_FEEDBACK_HUB;

package/src/bongos/upgrade-request.js

@@ -0,0 +1,158 @@
+'use strict';
+
+// src/bongos/upgrade-request.js — "Ask for this upgrade" on Settings → Software update
+// (task 1004595).
+//
+// WHY. A project that Cloud Bongos hosts is upgraded by the people who run its server,
+// not by its owner. Its Settings page said "Update ready" and then nothing: no button,
+// no next step (Will, mercury, 2026-10-06, 46 versions behind with nobody told). This
+// file gives that owner one press that reaches the operator, and remembers that it was
+// pressed so the page can say the request is pending.
+//
+// THE CHANNEL IS ONE THAT ALREADY EXISTS: the direct feedback door (task 1004591). The
+// project issues a one-time receipt for the signed-in builder in its OWN receipt store
+// (src/bongos/routes/feedback.js), then posts the request straight to the hub's
+// POST /api/bongos/sso/feedback/direct. The hub redeems the receipt at this project's
+// public URL, so the request lands in the maintainers' backlog attributed to the person
+// who really pressed the button, with no new credential and no new hub route.
+//
+// ONE REQUEST PER TARGET VERSION. Asking again for a version already asked for is
+// answered from the stored row and sends nothing. A different version may be asked for
+// once the cooldown has passed, so a project that falls further behind can say so,
+// without a press per patch release flooding the backlog.
+
+const crypto = require('node:crypto');
+
+const SETTING_KEY = 'software_update.request';
+const COOLDOWN_MS = 24 * 60 * 60 * 1000;
+const HUB_TIMEOUT_MS = 15000;
+
+const VERSION_RE = /^\d{1,4}\.\d{1,5}\.\d{1,6}$/;
+const LOGIN_RE = /^[A-Za-z0-9-]{1,39}$/;
+
+// The host this hall answers on, as the hub will need it to redeem the receipt: a bare
+// public DNS name. Anything else (an IP, a port, localhost, a dev name) cannot be
+// reached by the hub, so it is not askable. Mirrors the hub's own projectOrigin check.
+function projectHost(raw) {
+  const host = String(raw || '').trim().toLowerCase();
+  if (!/^[a-z0-9-]+(\.[a-z0-9-]+)+$/.test(host)) return null;
+  if (/^\d+(\.\d+)+$/.test(host)) return null;
+  if (/(^|\.)(localhost|local|internal|test|invalid)$/.test(host)) return null;
+  return host;
+}
+
+function hubHostOf(hub) {
+  try { return new URL(String(hub)).host.toLowerCase(); } catch { return null; }
+}
+
+// Is this a project the hub's operator runs? Its door is the hub's, or it answers on a
+// name under the hub's own domain (the same rule the hub uses to call a sender "verified").
+function isOperatorRun({ doorKind, host, hub }) {
+  if (doorKind === 'local' || !hub) return false;
+  if (doorKind === 'hub') return true;
+  const h = hubHostOf(hub);
+  return !!(h && host && (host === h || host.endsWith(`.${h}`)));
+}
+
+// The stored request, or null. A row this file did not write reads as no request.
+function parseStored(row) {
+  if (!row || typeof row.value !== 'string') return null;
+  let v;
+  try { v = JSON.parse(row.value); } catch { return null; }
+  if (!v || !VERSION_RE.test(String(v.version || ''))) return null;
+  const at = Date.parse(v.requested_at);
+  if (!Number.isFinite(at)) return null;
+  return {
+    version: String(v.version),
+    requested_at: new Date(at).toISOString(),
+    by: typeof v.by === 'string' && LOGIN_RE.test(v.by) ? v.by : null,
+  };
+}
+
+// What the page needs: may it offer the button, and what was asked before.
+// `ask_again_after` is when a request for a DIFFERENT version would be taken.
+function askState({ offered, host, doorKind, hub, stored }) {
+  const available = !!offered && isOperatorRun({ doorKind, host, hub }) && !!projectHost(host);
+  const ask = { available, hub_host: hub ? hubHostOf(hub) : null, requested: stored || null, ask_again_after: null };
+  if (stored) ask.ask_again_after = new Date(Date.parse(stored.requested_at) + COOLDOWN_MS).toISOString();
+  return ask;
+}
+
+// The text the operator reads. Its first line becomes the hub task's title.
+function requestMessage({ host, running, wanted, login }) {
+  const who = login && LOGIN_RE.test(login) ? `@${login}` : 'its owner';
+  return [
+    `Upgrade request: ${host} asks for core ${wanted} (it runs ${running || 'an unknown version'})`,
+    '',
+    `${who} pressed "Ask for this upgrade" in Settings, Software update on ${host}.`,
+    'This project cannot upgrade itself: the people who run its server do it.',
+    `Move its core to ${wanted} or newer, or tell them when it will be.`,
+  ].join('\n');
+}
+
+/**
+ * Send one upgrade request, or answer from the stored one. Never throws for an
+ * expected refusal; returns { status, body } for the route to send.
+ *
+ * deps: { hub, issueReceipt(receipt) → id|null, fetchImpl, getSetting, setSetting, now }
+ */
+async function requestUpgrade({ host, running, wanted, builder, doorKind }, deps) {
+  const now = deps.now || Date.now;
+  const hub = deps.hub;
+  const target = projectHost(host);
+  if (!wanted || !VERSION_RE.test(String(wanted))) return { status: 409, body: { error: 'nothing_to_ask', message: 'This project is up to date.' } };
+  if (!target || !isOperatorRun({ doorKind, host: target, hub })) {
+    return { status: 409, body: { error: 'not_operator_run', message: 'This project is not upgraded by an operator, so there is no one to ask.' } };
+  }
+
+  const stored = parseStored(await deps.getSetting(SETTING_KEY));
+  if (stored && stored.version === wanted) return { status: 200, body: { ok: true, already: true, request: stored } };
+  if (stored && now() < Date.parse(stored.requested_at) + COOLDOWN_MS) {
+    const retry = Math.ceil((Date.parse(stored.requested_at) + COOLDOWN_MS - now()) / 1000);
+    return { status: 429, body: { error: 'asked_recently', message: 'This project already asked for an upgrade today. Ask again tomorrow.', retry_after_seconds: retry, request: stored } };
+  }
+
+  const login = builder && typeof builder.github_login === 'string' && LOGIN_RE.test(builder.github_login) ? builder.github_login : null;
+  const message = requestMessage({ host: target, running, wanted, login });
+  const sha256 = crypto.createHash('sha256').update(message, 'utf8').digest('hex');
+  const receipt = deps.issueReceipt({
+    github_id: String(builder && builder.github_id),
+    github_login: login,
+    sha256,
+    kind: 'bug',
+    core_version: running || null,
+  });
+  if (!receipt) return { status: 429, body: { error: 'rate_limited', message: 'Too many requests just now. Try again in ten minutes.', retry_after_seconds: 600 } };
+
+  let res;
+  try {
+    res = await (deps.fetchImpl || fetch)(`${String(hub).replace(/\/+$/, '')}/api/bongos/sso/feedback/direct`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+      body: JSON.stringify({ origin: `https://${target}`, receipt, message, kind: 'bug', context: {} }),
+      redirect: 'error',
+      signal: AbortSignal.timeout(HUB_TIMEOUT_MS),
+    });
+  } catch {
+    return { status: 502, body: { error: 'operator_unreachable', message: 'Could not reach the people who run this project. Try again in a few minutes.' } };
+  }
+  if (res.status === 429) return { status: 429, body: { error: 'rate_limited', message: 'Too many requests just now. Try again in an hour.', retry_after_seconds: 3600 } };
+  if (res.status !== 202) {
+    return { status: 502, body: { error: 'operator_unreachable', message: `The request was not taken (HTTP ${res.status}). Try again later.` } };
+  }
+
+  const request = { version: String(wanted), requested_at: new Date(now()).toISOString(), by: login };
+  await deps.setSetting(SETTING_KEY, JSON.stringify(request), builder && builder.id != null ? builder.id : null);
+  return { status: 201, body: { ok: true, already: false, request } };
+}
+
+module.exports = {
+  SETTING_KEY,
+  COOLDOWN_MS,
+  projectHost,
+  isOperatorRun,
+  parseStored,
+  askState,
+  requestMessage,
+  requestUpgrade,
+};

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