@bongos/core 1.21.70 → 1.21.72

package/tests/goal_spec_task_db.mjs

@@ -0,0 +1,95 @@
+// tests/goal_spec_task_db.mjs — a goal made in the hall carries its own spec task,
+// and its other work waits behind it (task 1004585, ADR 0366 D3). REAL DB: the
+// claim gate and the auto-promotion are the database's, so this proves the edge
+// gateOnSpecTask writes is one they actually honour.
+//
+// Real-DB integration test (self-skips without a reachable Postgres; in the
+// INTEGRATION set so the default DB-free lane never runs it).
+//
+// Run:  DATABASE_URL=... node tests/goal_spec_task_db.mjs
+
+import { createRequire } from 'node:module';
+import { strict as assert } from 'node:assert';
+const require = createRequire(import.meta.url);
+const { Pool } = require('pg');
+
+const pool = new Pool({ connectionString: process.env.DATABASE_URL || undefined });
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`goal_spec_task_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}).`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+const db = require('../modules/lifecycle/db.js');
+const spec = require('../modules/lifecycle/goal-spec-task.js');
+
+const VER = 'ZZZ-SPEC', WORKER = 90000401;
+const q = (sql, params) => pool.query(sql, params).then((r) => r.rows);
+
+async function cleanup() {
+  const ids = (await q(`SELECT id FROM tasks WHERE version_id=$1`, [VER]).catch(() => [])).map((r) => r.id);
+  await q(`DELETE FROM claims WHERE task_id = ANY($1::bigint[])`, [ids]).catch(() => {});
+  await q(`DELETE FROM credit_log WHERE builder_id=$1 OR task_id = ANY($2::bigint[])`, [WORKER, ids]).catch(() => {});
+  await q(`DELETE FROM builder_achievements WHERE builder_id=$1`, [WORKER]).catch(() => {});
+  await q(`DELETE FROM dependencies WHERE (from_kind='task' AND from_id = ANY($1::bigint[])) OR (to_kind='task' AND to_id = ANY($1::bigint[]))`, [ids]).catch(() => {});
+  await q(`DELETE FROM tasks WHERE version_id=$1`, [VER]).catch(() => {});
+  await q(`DELETE FROM goal_members WHERE goal_id IN (SELECT id FROM goals WHERE version_id=$1)`, [VER]).catch(() => {});
+  await q(`DELETE FROM goals WHERE version_id=$1`, [VER]).catch(() => {});
+  await q(`DELETE FROM builders WHERE id=$1`, [WORKER]).catch(() => {});
+  await q(`DELETE FROM versions WHERE id=$1`, [VER]).catch(() => {});
+}
+
+let pass = 0;
+const ok = (cond, msg) => { assert.ok(cond, msg); console.log(`  ok  ${msg}`); pass++; };
+const statusOf = async (id) => (await q(`SELECT status FROM tasks WHERE id=$1`, [id]))[0].status;
+const edges = async (id) => (await q(`SELECT to_id FROM dependencies WHERE from_kind='task' AND from_id=$1 AND to_kind='task'`, [id])).map((r) => Number(r.to_id));
+
+try {
+  await cleanup();
+  await q(`INSERT INTO versions (id,name,status,track) VALUES ($1,'spec','building','internal') ON CONFLICT (id) DO NOTHING`, [VER]);
+  await q(`INSERT INTO builders (id,github_id,github_login,display_name,rank) VALUES ($1,'spec-w','spec-worker','Spec Worker','archon')`, [WORKER]);
+
+  // A hall-made goal and its spec task (what POST /goals { spec_task: true } writes).
+  const goal = await db.createGoal({ versionId: VER, title: 'Hall goal', createdBy: WORKER });
+  const specTask = await db.createTask(spec.specTaskFields(goal, { createdBy: WORKER }));
+  ok(specTask.status === 'ready' && specTask.kind === 'spike', 'the spec task is born ready, a spike');
+  ok((await edges(specTask.id)).length === 0, 'the spec task does not wait on itself');
+
+  // 1) A task filed into the goal waits on the spec task, and the claim gate says so.
+  const work = await db.createTask({ versionId: VER, goalId: goal.id, title: 'Build the first page', kind: 'feature', discipline: 'engineer', creditsReward: 10 });
+  ok((await edges(work.id)).includes(Number(specTask.id)), 'a filed task carries an edge to the spec task');
+  // unsatisfiedDeps is the read the claim gate refuses on (db-claims.js: a non-empty
+  // answer throws DEPS_NOT_SHIPPED). The full claim path is not driven here — its own
+  // DB test (claim_gate_open_blocker) is parked in this lane for unrelated setup.
+  const gating = await db.unsatisfiedDeps(work.id);
+  ok(gating.some((d) => d.kind === 'task' && Number(d.id) === Number(specTask.id)), 'the claim gate read names the spec task as unshipped');
+
+  // 2) Shipping the spec task releases it: the auto-promotion trigger moves it to ready.
+  await q(`UPDATE tasks SET status='shipped' WHERE id=$1`, [specTask.id]);
+  ok((await db.unsatisfiedDeps(work.id)).length === 0, 'nothing gates the task once the spec ships');
+  ok((await statusOf(work.id)) === 'ready', `the waiting task auto-promotes to ready (got ${await statusOf(work.id)})`);
+
+  // 3) A task filed after the spec shipped waits on nothing.
+  const later = await db.createTask({ versionId: VER, goalId: goal.id, title: 'Build the second page', kind: 'feature', discipline: 'engineer' });
+  ok((await edges(later.id)).length === 0, 'a shipped spec gates nothing new');
+
+  // 4) A goal made WITHOUT a spec task behaves exactly as before.
+  const plain = await db.createGoal({ versionId: VER, title: 'CLI goal', createdBy: WORKER });
+  const plainTask = await db.createTask({ versionId: VER, goalId: plain.id, title: 'Build the third page', kind: 'feature', discipline: 'engineer' });
+  ok((await edges(plainTask.id)).length === 0, 'a goal with no spec task adds no edge');
+
+  // 5) A task MOVED into a goal with an open spec task waits on it too.
+  const goal2 = await db.createGoal({ versionId: VER, title: 'Second hall goal', createdBy: WORKER });
+  const spec2 = await db.createTask(spec.specTaskFields(goal2, { createdBy: WORKER }));
+  await db.updateTaskGoal(plainTask.id, goal2.id);
+  ok((await edges(plainTask.id)).includes(Number(spec2.id)), 'a moved-in task carries an edge to the open spec task');
+
+  console.log(`\n${pass} passed, 0 failed`);
+} finally {
+  await cleanup();
+  await pool.end();
+}

package/tests/projects_hub_cloud_hop.mjs

@@ -0,0 +1,303 @@
+// tests/projects_hub_cloud_hop.mjs
+//
+// The create wizard's done panel in two moments (task 1004578, from idea 1001205):
+// WAIT — one status line, a thin bar and the cloud hop, a little game with one
+// cloud per PUBLIC project on the platform — then ARRIVE — the steps only the
+// founder can play, one at a time. The owner set the game's rules on a played
+// prototype, and the nausea ones are the ones a refactor would quietly lose: the
+// clouds stand still, the sky stands still, the view does not follow a jump.
+//
+// EXECUTED by the vm-slice idiom: momentFor/setMoment ride the same region the DNS
+// test runs (renderProgress); the physics (hopStep), the score line (hopScore),
+// the status sync (hopSync) and the pager (stepsPaint) are sliced function by
+// function and run under narrow stubs. Every slice is asserted to exist, so a
+// rename fails loudly instead of testing nothing. vm-born values are compared as
+// primitives or through JSON.
+//
+// Run:  node --test tests/projects_hub_cloud_hop.mjs
+
+import { test } from 'node:test';
+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';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+const HUB = fs.readFileSync(path.join(LANDING, 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+const STYLE = HUB.slice(HUB.indexOf('<style>'), HUB.indexOf('</style>'));
+const J = (v) => JSON.parse(JSON.stringify(v));
+
+function between(from, to) {
+  const a = SCRIPT.indexOf(from);
+  const b = SCRIPT.indexOf(to, a + 1);
+  assert.ok(a > 0, `slice start must exist: ${from}`);
+  assert.ok(b > a, `slice end must follow it: ${to}`);
+  return SCRIPT.slice(a, b);
+}
+// one wizard-scope function, closed on the first `}` at the wizard's four-space indent
+function fn(name) {
+  const m = SCRIPT.match(new RegExp(`\\n {4}function ${name}\\([^)]*\\) \\{[\\s\\S]*?\\n {4}\\}`));
+  assert.ok(m, `function ${name}() must be findable in projects.html`);
+  return m[0];
+}
+const HOP_CONSTS = (SCRIPT.match(/\n {4}var HOP_GAP = [^\n]*\n/) || [''])[0];
+assert.ok(HOP_CONSTS.includes('HOP_JUMP'), 'the hop constants line must be findable');
+const HOP_REGION = between('/* ══ THE CLOUD HOP (task 1004578)', '/* ── the hub\'s three doors ── */');
+
+// ── the moment ──────────────────────────────────────────────────────────────────
+const PROGRESS = between('var PROG_FLOWS = {', 'function startProgress(');
+const OVERLAY = between('function verifiedAt(inst)', 'function chipMarkup(');
+
+function bootMoment() {
+  const attrs = {};
+  const panel = { setAttribute: (k, v) => { attrs[k] = v; } };
+  const sandbox = {
+    $: (id) => (id === 'panel-done' ? panel : null),
+    esc: (s) => String(s), projectPageLink: (l) => l, relTime: () => 'now', canRestart: () => false,
+    FRESH_MS: 1, LIVE_MOMENT_MS: 1, state: {}, paintInviteGate() {}, lastProgHtml: '',
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(PROGRESS + '\n' + OVERLAY, sandbox);
+  return { sandbox, attrs };
+}
+const NOW = () => new Date().toISOString();
+const live = { status: 'active', domain: 'mercury.cloudbongos.com', dns_resolves: true, last_verified_up: true, last_verified_at: NOW(), open_intent: null };
+
+test('the moment follows the same branches renderProgress speaks', () => {
+  const { sandbox } = bootMoment();
+  const m = (inst) => sandbox.momentFor(inst);
+  assert.equal(m({ status: 'requested' }), 'wait', 'filed: the hop');
+  assert.equal(m({ status: 'provisioning' }), 'wait', 'standing up: the hop');
+  assert.equal(m({ ...live, dns_resolves: false, last_verified_up: null }), 'wait', 'address still being set up: keep playing');
+  assert.equal(m({ ...live, last_verified_up: null }), 'wait', 'standing, not checked yet: keep playing');
+  assert.equal(m({ ...live, last_verified_up: false }), 'wait', 'not answering right now: keep playing');
+  assert.equal(m(live), 'arrive', 'answering on a resolved address: arrive');
+  assert.equal(m({ ...live, open_intent: { action: 'standup', state: 'running' } }), 'arrive',
+    'an intent renderProgress does not speak for (a running standup) falls through to the status');
+  assert.equal(m({ ...live, open_intent: { action: 'provision' } }), 'wait', 'a queued standup is still a wait');
+  assert.equal(m({ status: 'torn_down', open_intent: { action: 'provision' } }), 'wait', 'a queued revive is a wait');
+});
+
+test('a snag, an ending, a settings change or an addressless project keeps the plain panel', () => {
+  const { sandbox } = bootMoment();
+  const m = (inst) => sandbox.momentFor(inst);
+  assert.equal(m({ status: 'error' }), 'plain');
+  assert.equal(m({ status: 'tearing_down' }), 'plain');
+  assert.equal(m({ status: 'torn_down' }), 'plain');
+  assert.equal(m({ ...live, open_intent: { action: 'teardown' } }), 'plain');
+  assert.equal(m({ ...live, open_intent: { action: 'settings-apply', state: 'running' } }), 'plain');
+  assert.equal(m({ ...live, domain: null }), 'plain', 'no address will never answer — nothing to arrive at');
+});
+
+test('renderProgress sets the moment before it writes the strip, and only for a real read', () => {
+  const { sandbox, attrs } = bootMoment();
+  const nodes = { liveProgress: { innerHTML: '', querySelector: () => null }, 'done-h': { textContent: '' }, doneLede: { innerHTML: '' } };
+  sandbox.$ = ((orig) => (id) => nodes[id] || orig(id))(sandbox.$);
+  sandbox.renderProgress({ status: 'provisioning' });
+  assert.equal(attrs['data-moment'], 'wait');
+  sandbox.renderProgress(live);
+  assert.equal(attrs['data-moment'], 'arrive');
+  const body = fn('renderProgress');
+  assert.ok(body.indexOf('setMoment(momentFor(inst))') < body.indexOf('setProgress('), 'the moment is decided first');
+  assert.match(body, /if \(inst\) setMoment\(momentFor\(inst\)\);/, 'a null read never moves the panel');
+});
+
+test('the panel leaves the hop on a stopped watch and starts on it at renderDone', () => {
+  const sp = between('function startProgress(', 'function resetForNewProject(');
+  assert.equal((sp.match(/setMoment\('plain'\);/g) || []).length, 2, 'the ~33-minute hand-off and a gone instance both drop to plain');
+  assert.match(fn('renderDone'), /setMoment\('wait'\);/, 'a fresh done panel opens on the hop');
+  assert.match(fn('resetForNewProject'), /hopReset\(\);/, 'a second project starts with a fresh hop');
+});
+
+// ── the physics — the owner's rules ─────────────────────────────────────────────
+function bootHop({ clouds = 3, reduced = false } = {}) {
+  const score = { textContent: '' };
+  const sandbox = { $: (id) => (id === 'hopScore' ? score : null), REDUCED: reduced, Math };
+  vm.createContext(sandbox);
+  vm.runInContext(HOP_CONSTS + 'var hop = { w: 600, feed: [], clouds: [], best: 0, maxed: false, p: null, cam: 0, camT: 0, L: false, R: false };\n' +
+    fn('hopCloudX') + fn('hopCloudW') + fn('hopScore') + fn('hopStep'), sandbox);
+  const hop = sandbox.hop;
+  hop.clouds.push({ i: 0, base: true, y: 0 });
+  // one fixed column of clouds straight up the middle, so a plain jump lands
+  for (let i = 1; i <= clouds; i++) hop.clouds.push({ i, f: 0.5, cw: 100, y: -i * sandbox.HOP_GAP, name: 'P' + i, acc: 'sea' });
+  hop.p = { x: 300, y: -14, vy: 0, on: hop.clouds[0], face: 1 };
+  hop.cam = hop.camT = -340 * 0.8;
+  return { sandbox, hop, score };
+}
+function run(sb, frames) { for (let i = 0; i < frames; i++) sb.hopStep(1); }
+
+test('a jump lands on the cloud above and the best height counts it', () => {
+  const { sandbox, hop, score } = bootHop();
+  const before = J(hop.clouds.map((c) => [c.f, c.y]));
+  hop.p.vy = -sandbox.HOP_JUMP; hop.p.on = null;
+  run(sandbox, 80);
+  assert.equal(hop.p.on && hop.p.on.i, 1, 'landed on the first project cloud');
+  assert.equal(hop.best, 1);
+  assert.equal(score.textContent, 'Best: 1 of 3 projects');
+  assert.deepEqual(J(hop.clouds.map((c) => [c.f, c.y])), before, 'the clouds never move — moving clouds read as nausea');
+});
+
+test('the view holds still during a jump and glides only after the landing', () => {
+  const { sandbox, hop } = bootHop();
+  const cam0 = hop.cam;
+  hop.p.vy = -sandbox.HOP_JUMP; hop.p.on = null;
+  let airborneMoved = false;
+  for (let i = 0; i < 80 && !hop.p.on; i++) { sandbox.hopStep(1); if (!hop.p.on && Math.abs(hop.cam - cam0) > 0.01) airborneMoved = true; }
+  assert.equal(airborneMoved, false, 'no camera motion while the player is in the air');
+  assert.ok(hop.p.on, 'and it did land');
+  run(sandbox, 60);
+  assert.ok(hop.cam < cam0 - 10, 'once landed higher, the view glides up');
+});
+
+test('a miss falls, and the full-width base cloud always catches', () => {
+  const { sandbox, hop } = bootHop();
+  hop.p.on = hop.clouds[2]; hop.p.y = hop.clouds[2].y - 14; hop.best = 2;
+  hop.p.x = 600 - 10;   // walk off the right edge of a centred cloud
+  run(sandbox, 200);
+  assert.equal(hop.p.on && hop.p.on.base, true, 'it fell past the lower clouds and landed on Your planet');
+  assert.equal(hop.best, 2, 'falling never takes the best height away');
+});
+
+test('steering moves the player, held to the stage', () => {
+  const { sandbox, hop } = bootHop();
+  hop.R = true; run(sandbox, 500);
+  assert.equal(hop.p.x, 590, 'right stops 10px from the edge');
+  hop.R = false; hop.L = true; run(sandbox, 500);
+  assert.equal(hop.p.x, 10, 'and left at 10px');
+});
+
+test('past the last cloud: max projects reached, build more to jump more', () => {
+  const { sandbox, hop, score } = bootHop({ clouds: 1 });
+  hop.p.vy = -sandbox.HOP_JUMP; hop.p.on = null;
+  run(sandbox, 80);
+  assert.equal(hop.maxed, true);
+  assert.equal(score.textContent, 'Max projects reached — build more to jump more');
+  const jump = fn('hopJump');
+  assert.match(jump, /!hop\.maxed/, 'and the jumping stops');
+  assert.match(HOP_REGION, /'Max projects reached'/);
+  assert.match(HOP_REGION, /'Build more to jump more'/);
+});
+
+test('the clouds are the public planets only, in the map\'s colours', () => {
+  const feed = fn('hopLoadFeed');
+  assert.match(feed, /p\.orb === 'planet'/, 'never a private star or a stealth black hole');
+  assert.match(feed, /localeCompare\(String\(b\.origin\)\)/, 'the accent walk runs over the origin-sorted catalog, like assignAccents');
+  assert.match(feed, /ORB_ACCENT_NAMES\.indexOf\(p\.planet_accent\) !== -1 \? p\.planet_accent/, 'the owner\'s pick wins');
+  assert.match(fn('hopBuild'), /hop\.clouds\.length === 1/, 'no public project at all reads as max reached');
+});
+
+// ── motion and the world ────────────────────────────────────────────────────────
+test('the loop never runs under reduced motion; the rest frame is a full still sky', () => {
+  assert.match(fn('hopRunning'), /return !REDUCED && !document\.hidden && hop\.target === 'wait'/, 'the gate, like the map\'s skyActive (C9)');
+  const start = fn('hopStart');
+  assert.ok(start.indexOf('hopRunning()') < start.indexOf('requestAnimationFrame'), 'nothing is scheduled before the gate');
+  assert.match(start, /hopDraw\(performance\.now\(\)\)/, 'a stopped hop draws its still frame');
+  assert.equal((HOP_REGION.match(/requestAnimationFrame\(/g) || []).length, 4,
+    'the start, the frame (playing and curtain) and the curtain\'s kick-off — no other loop');
+  assert.match(fn('hopFrame'), /if \(!hopRunning\(\)\) \{ hopDraw\(now\); return; \}/,
+    'every frame re-asks the gate, so turning reduced motion on stops it');
+  assert.match(fn('hopMoment'), /!REDUCED && hop\.raf/, 'the curtain plays only from a running game');
+  assert.match(STYLE, /\.hop\.isStill \.hopRow\{display:none;\}/, 'reduced motion has nothing to steer');
+});
+
+test('the game reads its colours off the page tokens — no literal but white or black with alpha', () => {
+  const hexes = HOP_REGION.match(/#[0-9a-fA-F]{3,8}\b/g) || [];
+  assert.deepEqual(hexes, [], 'no hex in the hop');
+  // hopCss() is the builder ('rgba(' + a token's channels), not a colour
+  const literals = (HOP_REGION.match(/'rgba?\([^']*'/g) || []).filter((m) => m !== "'rgba('");
+  for (const m of literals) assert.match(m, /^'rgba\(0,0,0,/, `only a black scrim may be literal: ${m}`);
+  assert.match(HOP_REGION, /var HOP_WHITE = \[255, 255, 255\];/, 'white is the one other literal');
+  assert.match(fn('hopColors'), /hopRead\('var\(--' \+ nm \+ '\)'\)/, 'every colour resolves from a token');
+});
+
+// ── the status line and the arrival pager ───────────────────────────────────────
+function el(cls = []) {
+  const set = new Set(cls);
+  const attrs = {};
+  return {
+    classList: { contains: (c) => set.has(c), toggle: (c, on) => (on ? set.add(c) : set.delete(c)), add: (c) => set.add(c), remove: (c) => set.delete(c) },
+    setAttribute: (k, v) => { attrs[k] = v; }, getAttribute: (k) => attrs[k], attrs, hidden: false, textContent: '', style: {},
+  };
+}
+
+test('the status line and the bar read what the strip says', () => {
+  const st = { textContent: '' }, fill = { style: {} };
+  const sandbox = { $: (id) => ({ hopStatus: st, hopBarFill: fill })[id] || null, Math };
+  vm.createContext(sandbox);
+  vm.runInContext(fn('hopSync'), sandbox);
+  const strip = {
+    querySelector: (q) => (q === '.pnote' ? { textContent: 'Raising the server, database, and address — nothing needed from you.' } : q === '.stages li.now' ? {} : null),
+    querySelectorAll: (q) => ({ length: q === '.stages li' ? 3 : 1 }),
+  };
+  sandbox.hopSync(strip);
+  assert.equal(st.textContent, 'Raising the server, database, and address — nothing needed from you.');
+  assert.equal(fill.style.width, '50%', 'one done and one under way of three');
+  assert.match(fn('setProgress'), /hopSync\(el\)/, 'every strip write syncs the line');
+});
+
+function bootSteps(items, signin) {
+  const list = { children: items, querySelector: (q) => items.find((li) => q.includes(li.key) || (q === 'li.cur' && li.classList.contains('cur'))) || null };
+  const panel = el(signin ? ['hopSignin'] : []);
+  const nodes = { 'panel-done': panel, humanSteps: list, hopWhile: el(), stepCount: el(), stepBack: el(), stepNext: el() };
+  const sandbox = { $: (id) => nodes[id] || null, Math, Array };
+  vm.createContext(sandbox);
+  vm.runInContext('var stepIdx = -1, stepAuto = true;' + fn('stepsPaint') + fn('stepGo'), sandbox);
+  return { sandbox, nodes };
+}
+function li(key, cls = []) { const e = el(cls); e.key = key; e.focus = () => {}; return e; }
+
+test('the arrival shows one step at a time, opening on the first not yet done', () => {
+  const items = [li('github-repo', ['sdone']), li('oauth-app'), li('device-flow', ['slocked']), li('enter-hall', ['slocked'])];
+  const { sandbox, nodes } = bootSteps(items);
+  sandbox.stepsPaint(true);
+  assert.deepEqual(items.map((i) => i.classList.contains('cur')), [false, true, false, false]);
+  assert.equal(nodes.stepCount.textContent, 'Step 2 of 4');
+  assert.equal(items[1].attrs['data-n'], '02', 'the step on show carries its own number — a hidden step never counts');
+  assert.equal(nodes.stepBack.hidden, false);
+  assert.equal(nodes.stepNext.hidden, false);
+  // the checklist ticks itself: the step on show finishing moves the founder on
+  items[1].classList.add('sdone');
+  sandbox.stepsPaint();
+  assert.equal(nodes.stepCount.textContent, 'Step 3 of 4');
+  // once they page for themselves, their choice holds
+  sandbox.stepGo(-1);
+  items[2].classList.add('sdone');
+  sandbox.stepsPaint();
+  assert.equal(nodes.stepCount.textContent, 'Step 2 of 4');
+  sandbox.stepGo(1); sandbox.stepGo(1);
+  assert.equal(nodes.stepNext.hidden, true, 'no Continue past the last step');
+});
+
+test('while waiting, the sign-in step is offered only when it can be done', () => {
+  const open = bootSteps([li('github-repo'), li('oauth-app')]);
+  open.sandbox.stepsPaint();
+  assert.equal(open.nodes.hopWhile.hidden, false, 'a domain and a public platform: offer it');
+  const locked = bootSteps([li('github-repo'), li('oauth-app', ['slocked'])]);
+  locked.sandbox.stepsPaint();
+  assert.equal(locked.nodes.hopWhile.hidden, true, 'locked: nothing to offer');
+  const done = bootSteps([li('github-repo'), li('oauth-app', ['sdone'])]);
+  done.sandbox.stepsPaint();
+  assert.equal(done.nodes.hopWhile.hidden, true, 'already wired: nothing to offer');
+  const opened = bootSteps([li('github-repo'), li('oauth-app', ['sdone'])], true);
+  opened.sandbox.stepsPaint();
+  assert.equal(opened.nodes.hopWhile.hidden, false, 'but an open one keeps its door so it can be closed');
+});
+
+// ── the markup and the sheet ────────────────────────────────────────────────────
+test('the wait stands the strip, the locked checklist and the later lines down; the arrival pages', () => {
+  for (const id of ['hop', 'hopStatus', 'hopBarFill', 'hopCanvas', 'hopLeft', 'hopJump', 'hopRight', 'hopScore', 'hopWhile', 'hopSignin', 'stepPager', 'stepCount', 'stepBack', 'stepNext']) {
+    assert.ok(HUB.includes(`id="${id}"`), `#${id} is baked into the panel`);
+  }
+  const panel = HUB.slice(HUB.indexOf('id="panel-done"'), HUB.indexOf('</section>', HUB.indexOf('id="panel-done"')));
+  assert.ok(panel.indexOf('id="liveProgress"') < panel.indexOf('id="hop"') && panel.indexOf('id="hop"') < panel.indexOf('id="wizInvite"'),
+    'the hop sits where the strip was, above the invite');
+  assert.match(panel, /id="hopStatus" role="status" aria-live="polite"/, 'the line is the live region while the strip is hidden');
+  assert.match(STYLE, /#panel-done\[data-moment="wait"\] #liveProgress,/);
+  assert.match(STYLE, /#panel-done\[data-moment="wait"\]:not\(\.hopSignin\) #humanSteps\{display:none;\}/);
+  assert.match(STYLE, /#panel-done\[data-moment="arrive"\] \.humanSteps>li:not\(\.cur\)\{display:none;\}/);
+  assert.match(STYLE, /#panel-done\[data-moment="arrive"\] #liveProgress \.stages\{display:none;\}/, 'the arrival keeps the note with the address, not the dots');
+  assert.match(STYLE, /@media \(prefers-reduced-motion:no-preference\)\{\n {2}#panel-done\[data-moment="arrive"\] \.humanSteps>li\.cur,/, 'the arrival\'s fade-in is motion-gated');
+});

package/tests/provision_settings_apply.mjs

@@ -78,6 +78,7 @@ ${NEUTRAL_PREFIX}_LOGO_URL=
 ${NEUTRAL_PREFIX}_FOUNDING_BIRTH=
 ${NEUTRAL_PREFIX}_DEMO_PEOPLE=
 ${NEUTRAL_PREFIX}_DEMO_HOURS=
+${NEUTRAL_PREFIX}_HUB_UPGRADE_URL=
 `;
 
 t('replaces an existing KEY= line where it stands; every other line survives byte-for-byte', () => {
@@ -147,6 +148,8 @@ t('settingsEnvVarsFor: the runner pushes the SAME pair webEnvBody writes at stan
     [`${NEUTRAL_PREFIX}_LOOK_ACCENT`]: '', [`${NEUTRAL_PREFIX}_LOGO_URL`]: '',
     // the birth marker and a demo's box (task 1004506), empty on an un-stamped row
     [`${NEUTRAL_PREFIX}_FOUNDING_BIRTH`]: '', [`${NEUTRAL_PREFIX}_DEMO_PEOPLE`]: '', [`${NEUTRAL_PREFIX}_DEMO_HOURS`]: '',
+    // where the hall's Update button goes (task 1004608), empty when no hub origin resolves
+    [`${NEUTRAL_PREFIX}_HUB_UPGRADE_URL`]: '',
   });
   const body = P.webEnvBody(inst, {});
   for (const [k, v] of Object.entries(vars)) assert.match(body, new RegExp(`^${k}=${v}$`, 'm'), `${k} at standup`);
@@ -247,7 +250,7 @@ await ta('dry-run PLANS the patch: reads nothing real, writes NOTHING (no synthe
   assert.equal(r.ok, true);
   assert.equal(r.healthy, null, 'nothing ran, nothing observed');
   assert.equal(writes.length, 0, 'a dry-run must not plan a two-line overwrite of web.env');
-  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY, .*_JOIN_GRANT, .*_ARTIST_GATE, .*_SPEND_PAYER, .*_LOOK, .*_NIGHT_TINT, .*_ARTIST_GATE_SINCE, .*_LOOK_ACCENT, .*_LOGO_URL, .*_FOUNDING_BIRTH, .*_DEMO_PEOPLE, .*_DEMO_HOURS in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
+  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY, .*_JOIN_GRANT, .*_ARTIST_GATE, .*_SPEND_PAYER, .*_LOOK, .*_NIGHT_TINT, .*_ARTIST_GATE_SINCE, .*_LOOK_ACCENT, .*_LOGO_URL, .*_FOUNDING_BIRTH, .*_DEMO_PEOPLE, .*_DEMO_HOURS, .*_HUB_UPGRADE_URL in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
   assert.ok(cmds.some((c) => /restart spike/.test(c)), 'the restart is still in the plan');
   assert.ok(logs.some((l) => /dry-run — nothing ran/.test(l)), 'the closing line does not claim a restart happened');
 });
@@ -630,5 +633,26 @@ await ta('a failed write reports the error without the value', async () => {
   assert.ok(!r.error.includes(SECRET), r.error);
 });
 
+console.log('\nhubUpgradeEnvVarsFor — where a hosted project\'s Update button goes (task 1004608):');
+
+t('both tenant shapes get the hub door for THEIR slug; no other shape gets the key; it rides standup AND the push', () => {
+  const saved = process.env.PROVISION_HUB_ORIGIN;
+  process.env.PROVISION_HUB_ORIGIN = 'https://hub.example.com/';
+  try {
+    const key = `${NEUTRAL_PREFIX}_HUB_UPGRADE_URL`;
+    for (const shape of ['cloud-host', 'co-tenant']) {
+      const inst = { slug: 'mercury', port: 3009, hosting_shape: shape, target_ref: 'will/mercury' };
+      assert.deepEqual(require('../scripts/gds/provision-units.js').hubUpgradeEnvVarsFor(inst), { [key]: 'https://hub.example.com/deploy?project=mercury' }, shape);
+      assert.equal(P.settingsEnvVarsFor(inst)[key], 'https://hub.example.com/deploy?project=mercury', `${shape} push`);
+      assert.match(P.webEnvBody(inst, {}), new RegExp(`^${key}=https://hub\\.example\\.com/deploy\\?project=mercury$`, 'm'), `${shape} standup`);
+    }
+    for (const shape of ['byo-host', 'control-plane']) {
+      assert.deepEqual(require('../scripts/gds/provision-units.js').hubUpgradeEnvVarsFor({ slug: 'x', hosting_shape: shape }), {}, shape);
+    }
+  } finally {
+    if (saved === undefined) delete process.env.PROVISION_HUB_ORIGIN; else process.env.PROVISION_HUB_ORIGIN = saved;
+  }
+});
+
 console.log(`\nprovision_settings_apply: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/software_update.mjs

@@ -180,7 +180,8 @@ async function drive(deps) {
   const build = require('../src/bongos/routes/core-update.js');
   const express = require('express');
   const app = express();
-  app.use(build(deps));
+  // The ask state's stored row is the DB's; these tests never reach one (task 1004595).
+  app.use(build({ askDeps: () => ({ hub: 'https://cloudbongos.com', getSetting: async () => null }), ...deps }));
   auth.requireBuilder = saved;
   const server = app.listen(0);
   await new Promise((r) => server.once('listening', r));
@@ -205,6 +206,22 @@ test('a hosted project: the Update button goes to the hub\'s door for THIS proje
   assert.deepEqual(r.body.door, { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=hoodify-finance' });
 });
 
+// Task 1004608: Will's mercury (a cloud-host that keeps its own GitHub app) has no sign-in
+// federation, so the panel told its owner to run `bongos upgrade` on the platform's server.
+test('a hosted project that does not federate sign-in still gets the hub\'s door, from HUB_UPGRADE_URL', async () => {
+  const r = await drive({ softwareUpdate: async () => STUB_UPDATE, canUpdate: async () => true,
+    doorInputs: () => ({ provisioning: false, idp: null, hubUpgradeUrl: 'https://cloudbongos.com/deploy?project=mercury' }) });
+  assert.deepEqual(r.body.door, { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=mercury' });
+});
+
+test('HUB_UPGRADE_URL is taken only as a hub /deploy address; anything else stays the cli answer', async () => {
+  for (const bad of ['', 'javascript:alert(1)', 'https://evil.example/phish', 'https://cloudbongos.com/deploy?project=a b', '/deploy']) {
+    const r = await drive({ softwareUpdate: async () => STUB_UPDATE, canUpdate: async () => true,
+      doorInputs: () => ({ provisioning: false, idp: null, hubUpgradeUrl: bad }) });
+    assert.deepEqual(r.body.door, { kind: 'cli', url: null }, bad);
+  }
+});
+
 test('a self-hosted instance has no door to link, and says how it is upgraded instead', async () => {
   const r = await drive({ softwareUpdate: async () => STUB_UPDATE, canUpdate: async () => true, doorInputs: () => ({ provisioning: false, idp: null }) });
   assert.deepEqual(r.body.door, { kind: 'cli', url: null });

package/tests/start_env_guard.mjs

@@ -94,8 +94,8 @@ t('offers the wrong-instance escape hatch (bongos login)', () => {
 t('a hosted origin never routes to bongos dev', () => {
   for (const deps of [true, false]) {
     const card = instanceNotRunningCard({ origin: 'https://example-instance.cloudbongos.com', depsMissing: deps });
-    assert.ok(!/^\s*\d+\.\s*`bongos dev`/m.test(card), 'must not list `bongos dev` as a step');
-    assert.ok(/Don't run `bongos dev`/.test(card), 'must say plainly not to, and why');
+    assert.ok(!/^\s*\d+\.\s*`(npx )?bongos dev`/m.test(card), 'must not list `bongos dev` as a step');
+    assert.ok(/Don't run `npx bongos dev`/.test(card), 'must say plainly not to, and why');
     assert.ok(/empty database/.test(card), 'must name the consequence, not just forbid it');
   }
 });

package/tests/upgrade_operator.mjs

@@ -0,0 +1,105 @@
+// tests/upgrade_operator.mjs — on a project its operator runs, `bongos upgrade` from a
+// builder's own computer says who upgrades it and how to ask, with no server steps
+// (task 1004596).
+//
+// WHAT IS AT RISK. A builder on a hosted project ran `bongos upgrade` from their laptop and
+// got "cannot determine which database to migrate. Set PGDATABASE…". Their assistant then
+// wrote them server instructions full of guessed names for a machine they cannot reach.
+// This pins (1) the wording that replaces that dead end and (2) the condition that shows
+// it — including that it never fires where a database is known, which is the operator's
+// own run on the server.
+//
+// Run:  node --test tests/upgrade_operator.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const op = require('../scripts/gds/upgrade-operator.js');
+const upgrade = require('../scripts/gds/upgrade.js');
+
+const HUB = { kind: 'hub', url: 'https://hub.example.com/deploy?project=mercury', hall: 'https://mercury.example.com/builders' };
+
+test('the message says who upgrades it and how to ask — and nothing to run on a server', () => {
+  const msg = op.operatorRunMessage(HUB);
+  assert.match(msg, /^This project is upgraded by its operator, not from this computer\./);
+  assert.match(msg, /https:\/\/mercury\.example\.com\/builders\/settings#software-update/);
+  assert.match(msg, /bongos feedback "Please upgrade this project to the latest version"/);
+  assert.match(msg, /There are no server steps for you to take\./);
+  // None of what sent the last assistant down the wrong road.
+  for (const bad of [/PGDATABASE/, /ssh/i, /sudo/, /--health-url/, /--service/, /systemctl/, /<[a-z_-]+>/i, /log in to the server/i]) {
+    assert.doesNotMatch(msg, bad, `the operator message must not mention ${bad}`);
+  }
+  // Without a known hall it still names the place, in words.
+  assert.match(op.operatorRunMessage({ kind: 'hub' }), /Open Settings → Software update and use the button there\./);
+});
+
+test('a database known here (the server) → no message, and the project is never even asked', async () => {
+  let asked = false;
+  const door = await op.operatorRunsThisProject({ instanceDir: '/srv/x' }, {
+    resolveInstanceDb: () => ({ db: 'mercury', ran: true }),
+    readUpdateDoor: async () => { asked = true; return HUB; },
+  });
+  assert.equal(door, null);
+  assert.equal(asked, false, 'the operator\'s own run must not depend on any network answer');
+});
+
+test('no database here + the project says its door is the hub → operator-run', async () => {
+  for (const probe of [{ db: null, ran: true }, { db: null, ran: false }]) {
+    const door = await op.operatorRunsThisProject({ instanceDir: '/laptop/x' }, {
+      resolveInstanceDb: () => probe, readUpdateDoor: async () => HUB,
+    });
+    assert.deepEqual(door, HUB);
+  }
+});
+
+test('operatorNotice is the message exactly when the project is operator-run', async () => {
+  const deps = { resolveInstanceDb: () => ({ db: null, ran: true }) };
+  assert.equal(await op.operatorNotice({ instanceDir: '/x' }, { ...deps, readUpdateDoor: async () => HUB }), op.operatorRunMessage(HUB));
+  assert.equal(await op.operatorNotice({ instanceDir: '/x' }, { ...deps, readUpdateDoor: async () => ({ kind: 'cli' }) }), null);
+});
+
+test('no database here, but a self-hosted / provisioning project, or no answer → behave as before', async () => {
+  for (const answer of [{ kind: 'cli', url: null }, { kind: 'local', url: '/deploy' }, null]) {
+    const door = await op.operatorRunsThisProject({ instanceDir: '/laptop/x' }, {
+      resolveInstanceDb: () => ({ db: null, ran: true }), readUpdateDoor: async () => answer,
+    });
+    assert.equal(door, null, `door ${JSON.stringify(answer)} must not trigger the operator message`);
+  }
+});
+
+function capture(stream) {
+  const orig = stream.write.bind(stream);
+  let out = '';
+  stream.write = (chunk, ...rest) => { out += String(chunk); return true; };
+  return { text: () => out, restore: () => { stream.write = orig; } };
+}
+
+test('`bongos upgrade --to …` on an operator-run project refuses with the message before anything moves', async () => {
+  const err = capture(process.stderr);
+  let code;
+  try {
+    code = await upgrade.main(['--to', '99.0.0', '--dry-run'], { operatorNotice: async () => op.operatorRunMessage(HUB) });
+  } finally { err.restore(); }
+  assert.equal(code, 1);
+  assert.match(err.text(), /✖ This project is upgraded by its operator/);
+  assert.doesNotMatch(err.text(), /cannot determine which database/);
+});
+
+test('bare `bongos upgrade` keeps its pre-check result and adds who upgrades it', async () => {
+  const out = capture(process.stdout);
+  let code;
+  try {
+    code = await upgrade.main([], { cmdUpgrade: async () => 0, operatorNotice: async () => op.operatorRunMessage(HUB) });
+  } finally { out.restore(); }
+  assert.equal(code, 0, 'the pre-check exit code is unchanged');
+  assert.match(out.text(), /This project is upgraded by its operator/);
+
+  const quiet = capture(process.stdout);
+  try {
+    code = await upgrade.main([], { cmdUpgrade: async () => 1, operatorNotice: async () => null });
+  } finally { quiet.restore(); }
+  assert.equal(code, 1);
+  assert.doesNotMatch(quiet.text(), /upgraded by its operator/, 'not an operator-run project → no message');
+});