@bongos/core 1.21.70 → 1.21.71

package/tests/upgrade_request.mjs

@@ -0,0 +1,348 @@
+// tests/upgrade_request.mjs — "Ask for this upgrade" on Settings → Software update
+// (task 1004595).
+//
+// WHAT IS AT RISK. Will's mercury, a project the Cloud Bongos operator runs, said "Update
+// ready" and then nothing: no button, no next step. The fix gives its owner one press that
+// reaches the operator and then says it is pending. So these tests hold that:
+//   - the press is offered only on a project the hub's operator runs, never on a
+//     self-hosted one (there is nobody at the hub to do it);
+//   - it reaches the operator through the direct feedback door, with a receipt the
+//     project's PUBLIC redeem route will vouch for (the hub files nothing without it);
+//   - it is sent once per version, remembered, and the page then shows it pending;
+//   - nothing in this file touches the network or a database.
+//
+// Run:  node --test tests/upgrade_request.mjs
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const ur = require('../src/bongos/upgrade-request.js');
+const { makeReceiptStore } = require('../src/bongos/routes/feedback.js');
+
+const HUB = 'https://cloudbongos.com';
+const WILL = { id: '12', github_id: '4242', github_login: 'will-x' };
+const T0 = Date.parse('2026-10-06T21:00:00Z');
+
+/** A hub that records what it was sent and answers `status`. */
+function fakeHub(status = 202) {
+  const sent = [];
+  const fetchImpl = async (url, init) => { sent.push({ url, init, body: JSON.parse(init.body) }); return { status }; };
+  return { sent, fetchImpl };
+}
+/** project_settings in memory. */
+function fakeSettings(initial = null) {
+  const rows = new Map();
+  if (initial) rows.set(ur.SETTING_KEY, { key: ur.SETTING_KEY, value: JSON.stringify(initial) });
+  return {
+    rows,
+    getSetting: async (k) => rows.get(k) || null,
+    setSetting: async (k, v, by) => { const r = { key: k, value: String(v), updated_by: by }; rows.set(k, r); return r; },
+  };
+}
+function deps({ hub = fakeHub(), settings = fakeSettings(), store = makeReceiptStore(), now = () => T0 } = {}) {
+  return { hub: HUB, fetchImpl: hub.fetchImpl, getSetting: settings.getSetting, setSetting: settings.setSetting, issueReceipt: (r) => store.issue(r), now, _hub: hub, _settings: settings, _store: store };
+}
+const ASK = { host: 'mercury.cloudbongos.com', running: '1.21.20', wanted: '1.21.66', builder: WILL, doorKind: 'cli' };
+
+// ---- who is offered the press -------------------------------------------------------
+
+test('offered on a project the hub runs (by its door, or by its name under the hub), never on a self-hosted one', () => {
+  const base = { offered: '1.21.66', hub: HUB, stored: null };
+  assert.equal(ur.askState({ ...base, host: 'mercury.cloudbongos.com', doorKind: 'cli' }).available, true, 'Will\'s mercury: no door, hosted name');
+  assert.equal(ur.askState({ ...base, host: 'shop.example.org', doorKind: 'hub' }).available, true, 'a hosted project on its own domain, with a hub door');
+  assert.equal(ur.askState({ ...base, host: 'shop.example.org', doorKind: 'cli' }).available, false, 'self-hosted: nobody at the hub upgrades it');
+  assert.equal(ur.askState({ ...base, host: 'cloudbongos.com', doorKind: 'local' }).available, false, 'the platform runs its own door');
+  assert.equal(ur.askState({ ...base, host: 'mercury.cloudbongos.com', doorKind: 'cli', hub: null }).available, false, 'no hub to ask');
+  assert.equal(ur.askState({ ...base, offered: null, host: 'mercury.cloudbongos.com', doorKind: 'cli' }).available, false, 'up to date: nothing to ask for');
+  assert.equal(ur.askState({ ...base, host: 'localhost:4600', doorKind: 'hub' }).available, false, 'a host the hub cannot reach to check the receipt');
+});
+
+// ---- the press itself ---------------------------------------------------------------
+
+test('a press reaches the operator through the direct feedback door, and is remembered', async () => {
+  const d = deps();
+  const out = await ur.requestUpgrade(ASK, d);
+  assert.equal(out.status, 201);
+  assert.deepEqual(out.body.request, { version: '1.21.66', requested_at: new Date(T0).toISOString(), by: 'will-x' });
+
+  assert.equal(d._hub.sent.length, 1);
+  const { url, body, init } = d._hub.sent[0];
+  assert.equal(url, `${HUB}/api/bongos/sso/feedback/direct`);
+  assert.equal(init.redirect, 'error');
+  assert.equal(body.origin, 'https://mercury.cloudbongos.com', 'the hub redeems the receipt at this project');
+  assert.equal(body.kind, 'bug');
+  assert.match(body.message.split('\n')[0], /^Upgrade request: mercury\.cloudbongos\.com asks for core 1\.21\.66 \(it runs 1\.21\.20\)$/);
+  assert.match(body.message, /@will-x pressed "Ask for this upgrade"/);
+
+  // The receipt is the one the hub will redeem: same sender, same text hash.
+  const receipt = d._store.redeem(body.receipt);
+  assert.equal(receipt.github_id, '4242');
+  assert.equal(receipt.github_login, 'will-x');
+  assert.equal(receipt.sha256, crypto.createHash('sha256').update(body.message, 'utf8').digest('hex'));
+  assert.equal(receipt.kind, 'bug');
+
+  const stored = ur.parseStored(d._settings.rows.get(ur.SETTING_KEY));
+  assert.deepEqual(stored, out.body.request, 'remembered, so the page can say it is pending');
+  assert.equal(d._settings.rows.get(ur.SETTING_KEY).updated_by, '12');
+});
+
+test('pressing again for the same version sends nothing and answers from the stored request', async () => {
+  const d = deps({ settings: fakeSettings({ version: '1.21.66', requested_at: '2026-09-01T00:00:00Z', by: 'will-x' }) });
+  const out = await ur.requestUpgrade(ASK, d);
+  assert.equal(out.status, 200);
+  assert.equal(out.body.already, true);
+  assert.equal(out.body.request.requested_at, '2026-09-01T00:00:00.000Z');
+  assert.equal(d._hub.sent.length, 0);
+});
+
+test('a newer version may be asked for, but not twice inside a day', async () => {
+  const recent = fakeSettings({ version: '1.21.60', requested_at: new Date(T0 - 3600e3).toISOString(), by: 'will-x' });
+  const d1 = deps({ settings: recent });
+  const out = await ur.requestUpgrade(ASK, d1);
+  assert.equal(out.status, 429);
+  assert.equal(out.body.error, 'asked_recently');
+  assert.match(out.body.message, /already asked for an upgrade today/, 'every refusal carries a sentence the page can show');
+  assert.equal(out.body.request.version, '1.21.60', 'the refusal carries the pending request, so the page can show it');
+  assert.equal(d1._hub.sent.length, 0);
+
+  const old = fakeSettings({ version: '1.21.60', requested_at: new Date(T0 - 2 * 86400e3).toISOString(), by: 'will-x' });
+  const d2 = deps({ settings: old });
+  assert.equal((await ur.requestUpgrade(ASK, d2)).status, 201);
+  assert.equal(d2._hub.sent.length, 1);
+});
+
+test('nothing is sent, and nothing remembered, when there is no one to ask or nothing to ask for', async () => {
+  for (const over of [{ doorKind: 'cli', host: 'shop.example.org' }, { doorKind: 'local' }, { wanted: null }, { wanted: '1.21.66"><b>' }]) {
+    const d = deps();
+    const out = await ur.requestUpgrade({ ...ASK, ...over }, d);
+    assert.equal(out.status, 409, JSON.stringify(over));
+    assert.equal(d._hub.sent.length, 0);
+    assert.equal(d._settings.rows.size, 0);
+  }
+});
+
+test('a hub that does not take it, or cannot be reached, leaves the request unasked so it can be pressed again', async () => {
+  for (const hub of [fakeHub(503), fakeHub(400), { sent: [], fetchImpl: async () => { throw new Error('ECONNRESET'); } }]) {
+    const d = deps({ hub });
+    const out = await ur.requestUpgrade(ASK, d);
+    assert.equal(out.status, 502);
+    assert.equal(out.body.error, 'operator_unreachable');
+    assert.equal(d._settings.rows.size, 0);
+  }
+  const limited = deps({ hub: fakeHub(429) });
+  const lim = await ur.requestUpgrade(ASK, limited);
+  assert.equal(lim.status, 429);
+  assert.match(lim.body.message, /Try again in an hour/);
+  assert.equal(limited._settings.rows.size, 0);
+});
+
+test('a stored row this file did not write reads as not asked', () => {
+  for (const value of ['', 'nope', '{}', JSON.stringify({ version: 'x', requested_at: '2026-10-01' }), JSON.stringify({ version: '1.2.3', requested_at: 'never' })]) {
+    assert.equal(ur.parseStored({ value }), null, value);
+  }
+  assert.equal(ur.parseStored({ value: JSON.stringify({ version: '1.2.3', requested_at: '2026-10-01T00:00:00Z', by: '<script>' }) }).by, null);
+});
+
+// ---- the receipt is redeemable at the project's PUBLIC route -------------------------
+
+test('the receipt the press issues is the one the public redeem route answers (one shared store)', async () => {
+  const fb = require('../src/bongos/routes/feedback.js');
+  const express = require('express');
+  const app = express();
+  app.use(require('../src/bongos/middleware/error-envelope.js').attachFail);
+  app.use(fb());
+  const hub = fakeHub();
+  const settings = fakeSettings();
+  const out = await ur.requestUpgrade(ASK, { hub: HUB, fetchImpl: hub.fetchImpl, getSetting: settings.getSetting, setSetting: settings.setSetting,
+    issueReceipt: (r) => fb.defaultReceiptStore().issue(r), now: () => T0 });
+  assert.equal(out.status, 201);
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  try {
+    const res = await fetch(`http://127.0.0.1:${server.address().port}/feedback/receipt/${hub.sent[0].body.receipt}`);
+    assert.equal(res.status, 200);
+    const body = await res.json();
+    assert.equal(body.github_id, '4242');
+    assert.equal(body.sha256, crypto.createHash('sha256').update(hub.sent[0].body.message, 'utf8').digest('hex'));
+  } finally { server.close(); }
+});
+
+// ---- the route ----------------------------------------------------------------------
+
+const ROUTE_SRC = fs.readFileSync(path.join(ROOT, 'src/bongos/routes/core-update.js'), 'utf8');
+
+test('[source] the press is gated on the same atom as the Update button', () => {
+  const at = ROUTE_SRC.indexOf("'/software-update/request'");
+  assert.ok(at > 0);
+  const seg = ROUTE_SRC.slice(at, ROUTE_SRC.indexOf("asyncHandler('POST /software-update/request'"));
+  assert.match(seg, /auth\.requireBuilder/);
+  assert.match(seg, /auth\.requirePermission\('core\.pin\.move'\)/);
+});
+
+async function serve(deps, { forwardedHost = 'evil.example' } = {}) {
+  const auth = require('../src/bongos/auth.js');
+  const saved = { b: auth.requireBuilder, p: auth.requirePermission };
+  auth.requireBuilder = (req, _res, next) => { req.builder = { ...WILL }; next(); };
+  auth.requirePermission = () => (_req, _res, next) => next();
+  const build = require('../src/bongos/routes/core-update.js');
+  const express = require('express');
+  const app = express();
+  app.use(express.json());
+  app.use((_req, res, next) => { res.fail = (code, o) => res.status(o.status).json({ error: { code, message: o.message || code, details: o.details } }); next(); });
+  try { app.use(build(deps)); } finally { auth.requireBuilder = saved.b; auth.requirePermission = saved.p; }
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  const base = `http://127.0.0.1:${server.address().port}`;
+  const call = async (method, p) => {
+    const res = await fetch(`${base}${p}`, { method, headers: { 'X-Forwarded-Host': forwardedHost, Host: forwardedHost, 'content-type': 'application/json' }, body: method === 'POST' ? '{}' : undefined });
+    return { status: res.status, body: await res.json() };
+  };
+  return { call, close: () => server.close() };
+}
+const UPDATE = { reading: 'ok', running: '1.21.20', offered: '1.21.66' };
+
+test('GET then POST then GET: offered, sent once, then shown as pending', async () => {
+  // A hub that takes a moment, so the two presses below truly overlap.
+  const hub = fakeHub();
+  const quick = hub.fetchImpl;
+  hub.fetchImpl = async (...a) => { await new Promise((r) => setTimeout(r, 40)); return quick(...a); };
+  const settings = fakeSettings();
+  const store = makeReceiptStore();
+  const s = await serve({
+    softwareUpdate: async () => UPDATE, selfChannel: async () => null, canUpdate: async () => true,
+    doorInputs: () => ({ provisioning: false, idp: null }),
+    askDeps: () => ({ hub: HUB, host: 'mercury.cloudbongos.com', fetchImpl: hub.fetchImpl, getSetting: settings.getSetting, setSetting: settings.setSetting, issueReceipt: (r) => store.issue(r) }),
+  });
+  try {
+    let r = await s.call('GET', '/software-update');
+    assert.equal(r.status, 200);
+    assert.deepEqual(r.body.door, { kind: 'cli', url: null });
+    assert.equal(r.body.ask.available, true);
+    assert.equal(r.body.ask.hub_host, 'cloudbongos.com');
+    assert.equal(r.body.ask.requested, null);
+
+    const [a, b] = await Promise.all([s.call('POST', '/software-update/request'), s.call('POST', '/software-update/request')]);
+    assert.deepEqual([a.status, b.status].sort(), [200, 201], 'a double press sends once; the second is answered from the row');
+    assert.equal(hub.sent.length, 1);
+    assert.equal(hub.sent[0].body.origin, 'https://mercury.cloudbongos.com',
+      'the call-back address is the project\'s own configured host, never the request\'s (X-Forwarded-Host: evil.example here)');
+
+    r = await s.call('GET', '/software-update');
+    assert.equal(r.body.ask.requested.version, '1.21.66');
+    assert.equal(r.body.ask.requested.by, 'will-x');
+  } finally { s.close(); }
+});
+
+test('the version asked for is the server\'s own reading, and a self-hosted project is refused', async () => {
+  const hub = fakeHub();
+  const settings = fakeSettings();
+  const askDeps = () => ({ hub: HUB, host: 'shop.example.org', fetchImpl: hub.fetchImpl, getSetting: settings.getSetting, setSetting: settings.setSetting, issueReceipt: () => 'r'.repeat(24) });
+  const common = { softwareUpdate: async () => UPDATE, selfChannel: async () => null, canUpdate: async () => true, doorInputs: () => ({ provisioning: false, idp: null }), askDeps };
+  // A self-hosted project whose caller claims a hosted name in the headers is still refused.
+  const self = await serve(common, { forwardedHost: 'mercury.cloudbongos.com' });
+  try {
+    const r = await self.call('POST', '/software-update/request');
+    assert.equal(r.status, 409);
+    assert.equal(r.body.error.code, 'not_operator_run');
+    assert.equal((await self.call('GET', '/software-update')).body.ask.available, false);
+    assert.equal(hub.sent.length, 0);
+  } finally { self.close(); }
+});
+
+// ---- the panel ----------------------------------------------------------------------
+
+const PANEL_SRC = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/settings-software-update.js'), 'utf8');
+const escapeHtml = (s) => String(s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+
+function bootPanel(answers) {
+  const el = (id) => ({ id, hidden: true, disabled: false, textContent: '', _html: '', dataset: {}, handlers: {},
+    set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; },
+    querySelectorAll: () => [], addEventListener(ev, fn) { this.handlers[ev] = fn; } });
+  const els = new Map(['software-update-scroll', 'su-body', 'su-note', 'settings-groups'].map((id) => [id, el(id)]));
+  els.get('settings-groups').dataset.active = 'update';
+  // Buttons drawn into su-body exist only while its html carries their id.
+  const dynamic = new Map();
+  const getElementById = (id) => {
+    if (els.has(id)) return els.get(id);
+    if (!els.get('su-body').innerHTML.includes(`id="${id}"`)) return null;
+    const key = `${id}@${els.get('su-body').innerHTML.length}:${els.get('su-body').innerHTML.slice(0, 40)}`;
+    if (!dynamic.has(key)) dynamic.set(key, el(id));
+    return dynamic.get(key);
+  };
+  const calls = [];
+  const windowObj = {
+    BongosClient: { createClient: () => ({ request: async (m, url, opts) => { calls.push({ m, url, opts }); return answers(m, url); } }) },
+    OTB: { escapeHtml },
+    location: { assign: () => {} },
+  };
+  const sandbox = { window: windowObj, document: { getElementById, addEventListener: () => {} }, console, setTimeout, Date, Math, URL, Promise, String, Number };
+  vm.createContext(sandbox);
+  vm.runInContext(PANEL_SRC, sandbox, { filename: 'settings-software-update.js' });
+  const settle = async () => { for (let i = 0; i < 10; i++) await new Promise((r) => setTimeout(r, 0)); };
+  return { calls, settle, body: () => els.get('su-body').innerHTML, byId: getElementById };
+}
+const ok = (data, status = 200) => ({ ok: status < 400, status, data });
+const PAGE = { ok: true, update: { reading: 'ok', running: '1.21.20', offered: '1.21.66', whats_new: null }, door: { kind: 'cli', url: null }, can_update: true,
+  ask: { available: true, hub_host: 'cloudbongos.com', requested: null, ask_again_after: null } };
+
+test('Will\'s page: who upgrades it, and an Ask button, never a server command', async () => {
+  const b = bootPanel(() => ok(PAGE));
+  await b.settle();
+  assert.match(b.body(), /the team at cloudbongos\.com looks after, so they install its updates/);
+  assert.match(b.body(), /id="su-ask">Ask for this upgrade</);
+  assert.doesNotMatch(b.body(), /bongos upgrade/);
+  assert.match(b.body(), /Update ready/);
+});
+
+test('pressing it sends the request and the page then says it is pending', async () => {
+  const request = { version: '1.21.66', requested_at: '2026-10-06T21:00:00.000Z', by: 'will-x' };
+  const b = bootPanel((m) => (m === 'POST' ? ok({ ok: true, already: false, request }, 201) : ok(PAGE)));
+  await b.settle();
+  await b.byId('su-ask').handlers.click();
+  await b.settle();
+  assert.deepEqual(b.calls.map((c) => `${c.m} ${c.url}`), ['GET /api/bongos/software-update', 'POST /api/bongos/software-update/request']);
+  assert.match(b.body(), /Upgrade requested on 6 October 2026 by @will-x, for version <span class="su-ver">1\.21\.66<\/span>\. The team at cloudbongos\.com has your request/);
+  assert.match(b.body(), /<span class="su-pill">Requested<\/span>/);
+  assert.doesNotMatch(b.body(), /id="su-ask"/, 'no second press offered');
+});
+
+test('a page loaded after asking shows it pending; a failed press says why and can be pressed again', async () => {
+  const asked = { ...PAGE, ask: { ...PAGE.ask, requested: { version: '1.21.66', requested_at: '2026-10-05T10:00:00Z', by: null }, ask_again_after: '2026-10-06T10:00:00Z' } };
+  const p = bootPanel(() => ok(asked));
+  await p.settle();
+  assert.match(p.body(), /Upgrade requested on 5 October 2026, for version/);
+  assert.doesNotMatch(p.body(), /id="su-ask"/);
+
+  const f = bootPanel((m) => (m === 'POST' ? ok({ error: { code: 'operator_unreachable', message: 'Could not reach the people who run this project. Try again in a few minutes.' } }, 502) : ok(PAGE)));
+  await f.settle();
+  const btn = f.byId('su-ask');
+  await btn.handlers.click();
+  await f.settle();
+  assert.equal(btn.disabled, false);
+  assert.equal(f.byId('su-ask-status').textContent, 'Could not send the request: Could not reach the people who run this project. Try again in a few minutes.');
+});
+
+test('a hosted project with a hub door keeps its Update button and offers asking as the fallback', async () => {
+  const b = bootPanel(() => ok({ ...PAGE, door: { kind: 'hub', url: 'https://cloudbongos.com/deploy?project=mercury' } }));
+  await b.settle();
+  assert.match(b.body(), /id="su-update" href="https:\/\/cloudbongos\.com\/deploy\?project=mercury"/);
+  assert.match(b.body(), /If that page does not let you in, ask the team at cloudbongos\.com/);
+  assert.match(b.body(), /class="pbtn pbtn--quiet" id="su-ask"/);
+});
+
+test('no ask for a viewer who may not upgrade, or where the server does not offer it', async () => {
+  const viewer = bootPanel(() => ok({ ...PAGE, can_update: false }));
+  await viewer.settle();
+  assert.doesNotMatch(viewer.body(), /id="su-ask"/);
+  const self = bootPanel(() => ok({ ...PAGE, ask: { ...PAGE.ask, available: false } }));
+  await self.settle();
+  assert.doesNotMatch(self.body(), /id="su-ask"/);
+  assert.match(self.body(), /<code>bongos upgrade<\/code>/);
+});

package/tests/upkeep_home.mjs

@@ -0,0 +1,156 @@
+// tests/upkeep_home.mjs — platform upkeep always has a home (task 1004597).
+//
+// THE BUG. On an instance whose goals are all product goals, a builder about to
+// upgrade the Bongos core tried to record it first (the ledger rule) and POST
+// /tasks refused `goal_id_required` (the goal rule) — none of the goals fit. The
+// session gave up rather than misfile. The two rules contradicted each other.
+//
+// THE FIX. A goal-less filing with an EXPLICIT kind 'infra' lands in the building
+// version's maintenance goal (the same find-or-create home ADR 0262 gives a
+// homeless bug). Anything else without a goal is still refused — and the refusal
+// now names that home and the exact flag to use.
+//
+// These drive the REAL POST /tasks handler with a stubbed lifecycle db, so the
+// wiring (not just the helper) is what is under test.
+//
+// Run:  node --test tests/upkeep_home.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+
+const { isUpkeepFiling, resolveUpkeepHome, UPKEEP_KIND } = require('../modules/lifecycle/upkeep-home.js');
+
+// ---- the rule ---------------------------------------------------------------
+
+test('only an explicit infra kind with no goal counts as upkeep', () => {
+  assert.equal(UPKEEP_KIND, 'infra');
+  assert.equal(isUpkeepFiling({ kind: 'infra' }), true);
+  assert.equal(isUpkeepFiling({ kind: 'infra', goal_id: 7 }), false, 'a named goal always wins');
+  for (const kind of [undefined, 'feature', 'bug', 'cleanup', 'unclassified']) {
+    assert.equal(isUpkeepFiling({ kind }), false, `${kind} must still name a goal — no silent bucket`);
+  }
+});
+
+test('resolveUpkeepHome finds-or-creates inside a transaction, and only for upkeep', async () => {
+  const calls = [];
+  const deps = {
+    withTx: async (fn) => { calls.push('tx'); return fn({ tx: true }); },
+    ensureMaintenanceGoal: async (v, { client }) => { calls.push([v, client.tx]); return { id: '42' }; },
+  };
+  assert.deepEqual(await resolveUpkeepHome({ kind: 'infra', version_id: 'V2' }, deps), { id: '42' });
+  assert.deepEqual(calls, ['tx', ['V2', true]], 'the advisory lock only holds inside a transaction');
+  calls.length = 0;
+  assert.equal(await resolveUpkeepHome({ kind: 'feature', version_id: 'V2' }, deps), null);
+  assert.equal(calls.length, 0, 'a non-upkeep filing never creates a goal');
+});
+
+// ---- the real route ----------------------------------------------------------
+
+const DB_PATH = require.resolve('../modules/lifecycle/db.js');
+const realDb = require(DB_PATH);
+
+// Load task-write-routes against a db whose goal/version/task calls are scripted,
+// capture the POST /tasks handler, and return a caller for it.
+function loadRoute({ versionStatus = 'building', maintenance = { id: '900', version_id: 'V2', status: 'open', is_maintenance: true } } = {}) {
+  const created = [];
+  const ensured = [];
+  const stub = {
+    ...realDb,
+    getVersion: async (id) => ({ id, status: versionStatus }),
+    findTaskBySourceRef: async () => null,
+    ensureMaintenanceGoal: async (v) => { ensured.push(v); return versionStatus === 'building' ? maintenance : null; },
+    getGoal: async (id) => (String(id) === String(maintenance.id) ? maintenance : { id, version_id: 'V2', status: 'open' }),
+    createTask: async (spec) => { created.push(spec); return { id: '1', goal_id: spec.goalId, touches: [], title: spec.title }; },
+    listCriteriaForGoal: async () => [],
+    getTaskCriteria: async () => [],
+    listOpenTasksWithTouches: async () => [],
+  };
+  const routePath = require.resolve('../modules/lifecycle/routes/task-write-routes.js');
+  const api = require('../src/module-api');
+  const realWithTx = api.withTx;
+  require.cache[DB_PATH].exports = stub;
+  delete require.cache[routePath];
+  const handlers = {};
+  try {
+    require(routePath)({
+      post: (p, ...h) => { handlers['POST ' + p] = h[h.length - 1]; },
+      patch: () => {}, get: () => {}, delete: () => {},
+    });
+  } finally {
+    require.cache[DB_PATH].exports = realDb;
+  }
+  async function call(body) {
+    // withTx must never reach a real pool here — hand ensureMaintenanceGoal a fake client.
+    api.withTx = async (fn) => fn({ fake: true });
+    const out = {};
+    const res = {
+      status(s) { out.status = s; return this; },
+      json(b) { out.body = b; return this; },
+      fail(code, opts) { out.status = typeof opts === 'number' ? opts : opts.status; out.body = { error: { code, message: opts.message } }; return this; },
+    };
+    try {
+      await handlers['POST /tasks']({ body, builder: { id: 1, rank: 'archon' } }, res);
+    } finally {
+      api.withTx = realWithTx;
+    }
+    return out;
+  }
+  return { call, created, ensured };
+}
+
+const UPGRADE = { version_id: 'V2', title: 'Upgrade the Bongos core to 1.21.70', description: 'Platform upkeep.', discipline: 'engineer' };
+
+test('an upgrade filed with kind infra and NO goal lands in the maintenance goal', async () => {
+  const { call, created, ensured } = loadRoute();
+  const out = await call({ ...UPGRADE, kind: 'infra' });
+  assert.equal(out.status, 201, JSON.stringify(out.body));
+  assert.deepEqual(ensured, ['V2'], 'the building version\'s maintenance goal is found or made');
+  assert.equal(created[0].goalId, 900, 'and the task is filed under it');
+  assert.equal(created[0].status, 'backlog', 'the status rules are untouched — no free ready work');
+  assert.equal(out.body.goal_home, 'maintenance', 'the caller is told where it went');
+});
+
+test('a goal-less filing that is NOT upkeep is still refused, and the refusal names the upkeep home', async () => {
+  const { call, created, ensured } = loadRoute();
+  const out = await call({ ...UPGRADE, kind: 'feature' });
+  assert.equal(out.status, 400);
+  assert.equal(out.body.error.code, 'goal_id_required');
+  assert.match(out.body.error.message, /kind "infra"/, 'names the exact way to file upkeep');
+  assert.match(out.body.error.message, /maintenance goal/);
+  assert.equal(created.length, 0);
+  assert.equal(ensured.length, 0, 'no goal is created for a refused filing');
+});
+
+test('upkeep against a version not being built is refused in words that say why', async () => {
+  const { call, created } = loadRoute({ versionStatus: 'planning' });
+  const out = await call({ ...UPGRADE, kind: 'infra' });
+  assert.equal(out.status, 400);
+  assert.equal(out.body.error.code, 'goal_id_required');
+  assert.match(out.body.error.message, /not being built/);
+  assert.equal(created.length, 0);
+});
+
+test('a named goal is used as-is, even for infra work', async () => {
+  const { call, created, ensured } = loadRoute();
+  const out = await call({ ...UPGRADE, kind: 'infra', goal_id: 55 });
+  assert.equal(out.status, 201);
+  assert.equal(ensured.length, 0);
+  assert.equal(created[0].goalId, 55);
+  assert.equal(out.body.goal_home, undefined);
+});
+
+// ---- the CLI ------------------------------------------------------------------
+
+test('bongos task new: the refusal tells a builder both ways forward in plain words', () => {
+  const { goalRequiredHelp } = require('../scripts/gds/task.js');
+  const help = goalRequiredHelp({ kind: 'feature', version_id: 'V2' });
+  assert.match(help, /--goal <id>/);
+  assert.match(help, /--kind infra and no --goal/);
+  assert.match(help, /Bongos upgrade/);
+  const stuck = goalRequiredHelp({ kind: 'infra', version_id: 'V0' });
+  assert.match(stuck, /not being built/);
+});