@bongos/core 1.21.69 → 1.21.71

package/scripts/gds/paste-token.js

@@ -86,7 +86,7 @@ const API_BASE = RESOLVED.base;
 function usage(extra) {
   if (extra) console.error(extra);
   console.error('');
-  console.error('Usage: bongos paste-token <token> [--api-base <url>]');
+  console.error('Usage: npx bongos paste-token <token> [--api-base <url>]');
   console.error('   (inside a core checkout: node scripts/gds/paste-token.js <token>)');
   console.error('');
   // Fall back to the inferred base for this hint when --api-base was the thing that

package/scripts/gds/provision-net.js

@@ -12,14 +12,7 @@
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { CONFIG } = require('./provision-config.js');
-const { provisionedEnvPrefix } = require('./provision-units.js');
-
-function federationHubOrigin() {
-  const explicit = process.env.PROVISION_HUB_ORIGIN;
-  if (explicit) return String(explicit).replace(/\/+$/, '');
-  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
-  return own ? String(own).replace(/\/+$/, '') : null;
-}
+const { federationHubOrigin, provisionedEnvPrefix } = require('./provision-units.js'); // lives beside the hub-upgrade address it also feeds (task 1004608)
 
 // Whether provisioning should federate this instance's sign-in through the hub.
 //

package/scripts/gds/provision-units.js

@@ -258,13 +258,15 @@ GITHUB_APP_PRIVATE_KEY=${String(appPem).replace(/\r?\n/g, '\\n')}
   // Postgres with every sibling and the control plane, so its pool may not take pg's
   // default 10 of the server's 97. src/bongos/pool.js reads it bare.
   const poolLine = `PGPOOL_MAX=${CONFIG.instancePoolMax}\n`;
+  // Where this project's Update button goes (task 1004608) — see hubUpgradeEnvVarsFor.
+  const hubUpgradeLines = Object.entries(hubUpgradeEnvVarsFor(inst)).map(([k, v]) => `${k}=${v}\n`).join('');
   return `# /etc/${inst.slug}/web.env — per-instance secrets (chmod 600, OUTSIDE the repo).
 ${credComment}
 ${prefix}_GITHUB_CLIENT_ID=${clientId || ''}
 ${prefix}_GITHUB_CLIENT_SECRET=${clientSecret || ''}
 ${firstAdminLine}${originLines}${appLines}PORT=${inst.port}
 PGDATABASE=${dbName(inst)}
-${poolLine}${dbLines}${fedLines}${settingsEnvLines(inst, prefix)}`;
+${poolLine}${dbLines}${fedLines}${hubUpgradeLines}${settingsEnvLines(inst, prefix)}`;
 }
 function webEnvPath(inst, { etcBase = CONFIG.etcBase } = {}) {
   return path.posix.join(etcBase, inst.slug, 'web.env');
@@ -295,7 +297,7 @@ function originEnvVarsFor(inst) {
 function settingsEnvVarsFor(inst, envBody) {
   const { settingsEnvVars } = require(path.join(REPO_ROOT, 'modules/provisioning/provisioning')); // eslint-disable-line global-require
   const prefix = inst && inst.hosting_shape === 'control-plane' ? selfEnvPrefix({ envBody }) : provisionedEnvPrefix();
-  return settingsEnvVars(inst, prefix);
+  return { ...settingsEnvVars(inst, prefix), ...hubUpgradeEnvVarsFor(inst) };
 }
 
 // The env-var prefix the CONTROL PLANE's own web process resolves (task 1004334). The
@@ -414,8 +416,32 @@ function renamedEnvCarry(body) {
 // <PREFIX>_HUB_ORIGIN (what auth.js loadIdpConfig reads). Explicit PROVISION_HUB_ORIGIN
 // wins; otherwise the control plane's OWN public origin (<PREFIX>_PUBLIC_ORIGIN, the
 // env the hub already runs under). Null → not hub-configured → shouldFederate is false.
+function federationHubOrigin() {
+  const explicit = process.env.PROVISION_HUB_ORIGIN;
+  if (explicit) return String(explicit).replace(/\/+$/, '');
+  const own = process.env[`${provisionedEnvPrefix()}_PUBLIC_ORIGIN`];
+  return own ? String(own).replace(/\/+$/, '') : null;
+}
+
+// WHERE A HOSTED PROJECT'S UPDATE BUTTON GOES (task 1004608): the hub's deploy door for
+// THIS project, written as <PREFIX>_HUB_UPGRADE_URL. The hall used to learn the hub only
+// from the sign-in federation block, which only a co-tenant gets, so every cloud-host
+// project (and any that keeps its own GitHub app) told its owner to run `bongos upgrade`
+// on a server the platform runs. The door admits the owner of both tenant shapes
+// (modules/provisioning/core-upgrade-authz.js), so both get the address. Not a secret and
+// grants nothing: the door re-checks every request. Empty for the tenant shapes when no hub
+// origin resolves (a key that came and went would leave a stale line behind); absent for
+// every other shape, which has no door on this hub.
+const HUB_UPGRADE_SHAPES = new Set(['co-tenant', 'cloud-host']);
+function hubUpgradeEnvVarsFor(inst) {
+  if (!inst || !HUB_UPGRADE_SHAPES.has(inst.hosting_shape) || !inst.slug) return {};
+  const origin = federationHubOrigin();
+  return { [`${provisionedEnvPrefix()}_HUB_UPGRADE_URL`]: origin ? `${origin}/deploy?project=${encodeURIComponent(String(inst.slug))}` : '' };
+}
 
 module.exports = {
+  federationHubOrigin,
+  hubUpgradeEnvVarsFor,
   ENV_PREFIX_PACK,
   envPrefixMismatch,
   normalizePackEnvPrefix,

package/scripts/gds/reauth.js

@@ -96,7 +96,7 @@ function printGuidance({ opened }) {
   console.log("        you're already signed in there via your browser cookie)");
   console.log('  2. Under the "CLI Access" section, click "Re-issue CLI token".');
   console.log('  3. Click "Copy" — it copies a one-line command that looks like:');
-  console.log('       bongos paste-token <token>');
+  console.log('       npx bongos paste-token <token>');
   console.log('  4. Paste that one line back to Claude. It will run it for you,');
   console.log('     verify the token, and write your new session.');
   console.log('');

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

@@ -106,6 +106,9 @@ const INTEGRATION = new Set([
   // never was a dedicated consumer-layout-boot workflow, whatever older notes say.
   'consumer_layout_boot',
   'claim_gate_open_blocker', 'claim_gate_rebase',
+  // task 1004585: a hall-made goal's spec task gates its other work — the edge, the
+  // claim gate's unsatisfiedDeps read, and the ship-time auto-promotion, on real Postgres.
+  'goal_spec_task_db',
   // task 1003457: proves the blocker-resolve auto-promotion trigger (migration
   // 009, tightened by core_223) fires on the HALL'S OWN write path — the real
   // buildGdsRouter() HTTP routes, not a static SQL-text pin (blocker_resolve_guard.mjs,

package/scripts/gds/setup.js

@@ -356,7 +356,7 @@ async function finishSetup(builder) {
       console.log(`  3. Claim + ship:      ${surfaceAction('claim', 'N')}    →    ${surfaceAction('ship')}`);
       // Claiming writes code, so it needs a checkout. In a terminal the public CLI answers
       // `bongos claim` with where to get one; say so here rather than let step 3 look self-serve.
-      if (isTerminalSurface()) console.log('     (claim + ship run in a checkout — `bongos claim` shows how to get one)');
+      if (isTerminalSurface()) console.log('     (claim + ship run in a checkout — `npx bongos claim` shows how to get one)');
       console.log('  4. Ship three works and you rise to Thetes — the whole queue opens.');
     }
   } catch (_) {

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/platform-visibility-gate.js

@@ -110,6 +110,9 @@ const EXEMPT = [
   /^\/downloads\//,
   { re: new RegExp(`^${API}/access-requests$`), methods: ['POST'] },
   { re: new RegExp(`^${API}/access-requests/status$`), methods: ['GET'] },
+  // The hub redeeming a `bongos feedback` receipt (task 1004591): it has no
+  // session here, and a members-only project must still vouch for its builders.
+  { re: new RegExp(`^${API}/feedback/receipt/[a-z0-9_-]+$`), methods: ['GET'] },
 ];
 
 // The policy, read through the memoized pack. A pack that cannot be read at all

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;