@bongos/core 1.20.79 → 1.20.80

package/modules/lifecycle/workflow-dispatch.js

@@ -0,0 +1,45 @@
+'use strict';
+
+// modules/lifecycle/workflow-dispatch.js — the one GitHub act another module may borrow.
+// Lent through the `lifecycle.workflowDispatch` port (routes/lifecycle.js); see ADR 0361.
+// Kept beside github-push.js rather than in it: it shares that file's credential and headers,
+// and nothing else.
+
+const { resolveToken, ghHeaders, isSafeBranch } = require('./github-push');
+const { repoInfo: { loadRepoInfo } } = require('../../src/module-api');
+
+// dispatchWorkflow — start a GitHub Actions workflow on this repo (task 1004298, ADR 0361). The
+// Release button on /deploy uses it to run publish.yml's release job, so the npm credential never
+// leaves GitHub: the server holds only the GitHub App key it already holds, and the App needs
+// Actions: write for this one call. Returns { ok:true } on GitHub's 204, otherwise
+// { ok:false, code, status? } — UNCONFIGURED (no credential), NO_REPO_INFO, BAD_INPUT, REFUSED
+// (GitHub said no: 403 = the App lacks Actions: write, 404 = no such workflow or no access,
+// 422 = an input the workflow does not declare), UNREACHABLE. Never throws.
+//
+// ONLY THE WORKFLOWS NAMED HERE can be started. The port lends the server's GitHub credential to
+// another module; an allowlist keeps a buggy or future borrower from running any other workflow in
+// the repo. Adding one is a reviewed edit to this line.
+const DISPATCHABLE_WORKFLOWS = Object.freeze(['publish.yml']);
+async function dispatchWorkflow({ workflow, ref = 'main', inputs = {} }, deps = {}) {
+  if (!DISPATCHABLE_WORKFLOWS.includes(String(workflow || '')) || !isSafeBranch(ref)) return { ok: false, code: 'BAD_INPUT' };
+  let token;
+  try { token = await resolveToken(deps); } catch (_) { return { ok: false, code: 'UNCONFIGURED' }; }
+  if (!token) return { ok: false, code: 'UNCONFIGURED' };
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  if (!repoInfo || repoInfo.error) return { ok: false, code: 'NO_REPO_INFO' };
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  try {
+    const res = await doFetch(`https://api.github.com/repos/${owner}/${repo}/actions/workflows/${workflow}/dispatches`, {
+      method: 'POST',
+      headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+      body: JSON.stringify({ ref, inputs }),
+    });
+    if (res.status === 204 || res.ok) return { ok: true };
+    return { ok: false, code: 'REFUSED', status: res.status };
+  } catch (_) {
+    return { ok: false, code: 'UNREACHABLE' };
+  }
+}
+
+module.exports = { dispatchWorkflow };

package/modules/npm-release/module.json

@@ -16,7 +16,8 @@
     "routes": [
       "work",
       "task-where",
-      "preview"
+      "preview",
+      "release"
     ],
     "uiSections": [
       "task-where"

package/modules/npm-release/public/work.js

@@ -136,6 +136,77 @@
       </li>`;
   }
 
+  // ---- the Release button (task 1004298) ---------------------------------------------------
+  //
+  // Merges publish as candidates: this hall runs each one, no other project is offered it. Release
+  // makes a version the one every other project is offered. Beside each button, the evidence the
+  // owner decides on — how long the version has run here, and whether it was ever rolled back —
+  // read by the server from this hall's upgrade ledger.
+  let releasing = '';
+  let releaseNote = null;   // { ok, text } — the last press's answer, shown until the next read
+
+  function hoursText(h) {
+    if (h == null) return 'not in this hall\'s upgrade ledger';
+    if (h < 1) return 'under an hour';
+    if (h < 48) return `${Math.round(h)} hour${Math.round(h) === 1 ? '' : 's'}`;
+    return `${Math.round(h / 24)} days`;
+  }
+
+  function candidateRow(c) {
+    const ran = c.on_hall_since == null
+      ? 'This hall\'s upgrade ledger does not show it going in.'
+      : c.still_running ? `Running here for ${hoursText(c.hours_on_hall)}.` : `Ran here for ${hoursText(c.hours_on_hall)} before a newer version replaced it.`;
+    const facts = [];
+    if (c.rolled_back) facts.push('<span class="ov-fact"><b>was rolled back here</b></span>');
+    if (c.still_running) facts.push('<span class="ov-fact">running now</span>');
+    const busy = releasing === c.version;
+    return `<li class="ov-row ov-row--dense${c.rolled_back ? ' nr-upgrade--back' : ''}">
+        <div class="ov-row__main">
+          <span class="ov-row__title ov-key">${escapeHtml(c.version)}</span>
+          <p class="ov-row__sub">${escapeHtml(ran)}${c.rolled_back ? ' A move to it did not come back healthy at least once, and was undone.' : ''}</p>
+          ${facts.length ? `<div class="ov-row__facts">${facts.join('')}</div>` : ''}
+        </div>
+        <div class="ov-row__right"><button type="button" class="ov-toggle" data-release="${escapeHtml(c.version)}"${releasing ? ' disabled' : ''}>${busy ? 'Starting…' : 'Release'}</button></div>
+      </li>`;
+  }
+
+  function releaseHtml(d) {
+    const r = d.release;
+    if (!r) return '';
+    let body;
+    if (!r.ok) body = `<p class="ov-row__sub">${escapeHtml(r.error || 'The registry could not be read')}, so nothing can be released right now.</p>`;
+    else if (!r.candidates.length) body = `<p class="ov-row__sub">Nothing is waiting: every version this hall runs is already released${d.released ? ` (the release is ${escapeHtml(d.released)})` : ''}.</p>`;
+    else body = `<ul class="ov-rows">${r.candidates.map(candidateRow).join('')}</ul>`;
+    const note = releaseNote ? `<div class="ov-note${releaseNote.ok ? '' : ' ov-note--warn'}"><p>${escapeHtml(releaseNote.text)}</p></div>` : '';
+    const ledger = r.ok && r.ledger_error ? `<p class="ov-row__sub">${escapeHtml(r.ledger_error)}.</p>` : '';
+    return `<div class="ov-group" data-release-section>
+        <div class="ov-group__head">
+          <span class="ov-group__name">Release</span>
+          ${r.ok ? `<span class="ov-group__n">${r.candidates.length}</span>` : ''}
+        </div>
+        <p class="ov-row__sub">New versions run here first and are offered to no other project. Release makes a version, and everything merged before it, what every other project is offered: their Settings, their banner, their automatic updates.${d.released ? ` Released now: ${escapeHtml(d.released)}.` : ''}</p>
+        ${note}${ledger}${body}
+      </div>`;
+  }
+
+  async function release(version) {
+    if (releasing) return;
+    if (!window.confirm(`Release ${version} to every project?\n\nEvery other project will be offered ${version} and everything merged before it. This cannot be pressed back; a newer version can be released after it.`)) return;
+    releasing = version;
+    releaseNote = null;
+    paint();
+    try {
+      const res = await client.request('POST', `${API}/npm-release/release`, { body: { version } });
+      const msg = (res.data && (res.data.message || (res.data.error && res.data.error.message))) || `release → ${res.status}`;
+      releaseNote = { ok: res.ok, text: msg };
+    } catch (e) {
+      releaseNote = { ok: false, text: `Nothing was released: ${e.message || e}` };
+    } finally {
+      releasing = '';
+      paint();
+    }
+  }
+
   function upgradesHtml(d) {
     const u = d.upgrades;
     if (!u) return '';
@@ -322,6 +393,7 @@
       ${problemsHtml(data)}
       ${figsHtml(stages, data)}
       ${groups || '<p class="ov-row__sub">Nothing was finished in this window.</p>'}
+      ${releaseHtml(data)}
       ${upgradesHtml(data)}
       <p class="ov-foot">read ${escapeHtml(new Date(data.checked_at).toLocaleTimeString())} · ${escapeHtml(data.package)} · release notes from ${escapeHtml(data.notes.source ? `${data.notes.source.from === 'package' ? 'the published' : 'this hall\'s'} ${data.notes.source.version} package` : 'nowhere')}</p>`;
     work.hidden = false;
@@ -398,6 +470,8 @@
     const ex = t.closest('[data-expand]');
     if (ex) { expanded.add(ex.getAttribute('data-expand')); paint(); return; }
     if (t.closest('#nr-older')) { loadOlder(); return; }
+    const rel = t.closest('[data-release]');
+    if (rel) { release(rel.getAttribute('data-release')); return; }
     const pv = t.closest('[data-preview]');
     if (pv) { previewAct(() => previewCall('POST', { version: pv.getAttribute('data-preview') })); return; }
     if (t.closest('[data-preview-stop]')) previewAct(() => previewCall('DELETE'));

package/modules/npm-release/release.js

@@ -0,0 +1,129 @@
+'use strict';
+
+// modules/npm-release/release.js — the Release button's half of the deploy page (task 1004298,
+// ADR 0361).
+//
+// Merges publish as CANDIDATES: on npm, run by this (the platform) hall, offered to no other project.
+// Release makes a version the one every other project is offered, by moving the registry's `latest`
+// label. The move itself happens in GitHub (publish.yml's release job), so the npm credential never
+// leaves GitHub; this server only asks GitHub to run it, through the lifecycle module's one-function
+// workflowDispatch port.
+//
+// TWO THINGS LIVE HERE:
+//   releaseCandidates — the evidence beside each button: how long the version has run on this hall,
+//                       and whether a move to it was ever rolled back here. Read from core_upgrades,
+//                       the ledger `bongos upgrade` writes on every move and rollback.
+//   requestRelease    — what the button does: the same rule the workflow applies (release-core.js,
+//                       imported, never restated), then the dispatch.
+
+const { releaseDecision } = require('../../scripts/gds/release-core.js');
+
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+// The ledger window the evidence reads. A candidate older than this has been superseded many
+// times over; the page shows the newest few.
+const LEDGER_DAYS = 60;
+const CANDIDATES_SHOWN = 5;
+const WORKFLOW = 'publish.yml';
+
+function compareVersions(a, b) {
+  const pa = String(a).split('.').map(Number);
+  const pb = String(b).split('.').map(Number);
+  for (let i = 0; i < 3; i++) if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0);
+  return 0;
+}
+
+// The version a rollback row says it ATTEMPTED: "rolled_back: <why> (attempted A → B, restored C)".
+function attemptedIn(note) {
+  const m = /\(attempted\s+\S+\s*→\s*(\d+\.\d+\.\d+)/.exec(String(note || ''));
+  return m ? m[1] : null;
+}
+
+/**
+ * PURE. The versions Release can be pressed on, newest first, each with its evidence.
+ *
+ * A candidate is a published version newer than the release and no newer than what this hall runs
+ * (a version this hall never ran has no evidence, and the hall runs every candidate by design).
+ *
+ * `rows`: core_upgrades rows, any order, { to_version, applied_at, note }. A row whose note begins
+ * `rolled_back:` is a rollback; every other row is a move that went in.
+ *   on_hall_since — when the version first went in here (null: the ledger does not show it);
+ *   hours_on_hall — from then until this hall moved past it, or until now if it still runs it;
+ *   rolled_back   — a move to it was rolled back here at least once.
+ */
+function releaseCandidates({ rows, versions, released, live, now = Date.now() } = {}) {
+  if (!VERSION_RE.test(String(live || ''))) return [];
+  const list = (Array.isArray(versions) ? versions : [])
+    .filter((v) => VERSION_RE.test(v))
+    .filter((v) => compareVersions(v, live) <= 0)
+    .filter((v) => !released || compareVersions(v, released) > 0)
+    .sort(compareVersions)
+    .reverse()
+    .slice(0, CANDIDATES_SHOWN);
+  const ledger = (Array.isArray(rows) ? rows : [])
+    .map((r) => ({ to: r.to_version || null, at: r.applied_at ? Date.parse(r.applied_at) : NaN, note: r.note == null ? '' : String(r.note) }))
+    .filter((r) => Number.isFinite(r.at))
+    .sort((a, b) => a.at - b.at);
+  const moves = ledger.filter((r) => !/^rolled_back:/.test(r.note));
+  const rollbacks = ledger.filter((r) => /^rolled_back:/.test(r.note));
+  return list.map((v) => {
+    const i = moves.findIndex((r) => r.to === v);
+    const since = i >= 0 ? moves[i].at : null;
+    const next = i >= 0 ? moves.slice(i + 1).find((r) => r.to !== v) : null;
+    const until = next ? next.at : now;
+    return {
+      version: v,
+      on_hall_since: since == null ? null : new Date(since).toISOString(),
+      hours_on_hall: since == null ? null : Math.max(0, Math.round(((until - since) / 3600000) * 10) / 10),
+      still_running: v === live,
+      rolled_back: rollbacks.some((r) => attemptedIn(r.note) === v),
+    };
+  });
+}
+
+async function readReleaseLedger(pool) {
+  try {
+    const { rows } = await pool.query(
+      `SELECT to_version, applied_at, note
+         FROM core_upgrades
+        WHERE applied_at > now() - ($1 || ' days')::interval
+        ORDER BY applied_at, id`,
+      [String(LEDGER_DAYS)]
+    );
+    return { ok: true, rows };
+  } catch (e) {
+    return { ok: false, error: e.message, rows: [] };
+  }
+}
+
+/**
+ * What the Release button does. Returns { status, body } for the route to send.
+ *
+ * The rule is release-core.js's releaseDecision — the one the workflow applies again before it
+ * moves anything, so the button cannot promise what the workflow would refuse. Refusals here save a
+ * GitHub run; they are not the gate (the workflow is).
+ */
+async function requestRelease({ version, registry, dispatch } = {}) {
+  if (!registry || !registry.ok) {
+    return { status: 503, body: { error: { code: 'registry_unreadable', message: 'The npm registry could not be read, so nothing was released. Try again in a minute.' } } };
+  }
+  const d = releaseDecision({ version, versions: registry.versions, latest: registry.latest });
+  if (d.noop) return { status: 200, body: { ok: true, noop: true, version, message: `${version} is already the release.` } };
+  if (!d.go) return { status: 409, body: { error: { code: 'not_releasable', message: `Not released: ${d.reason}. Pick a version from the Release list, which shows only the ones that can be released.` } } };
+  if (typeof dispatch !== 'function') {
+    return { status: 503, body: { error: { code: 'dispatch_unavailable', message: 'This hall cannot start GitHub workflows (the lifecycle module is not running), so nothing was released.' } } };
+  }
+  const r = await dispatch({ workflow: WORKFLOW, ref: 'main', inputs: { release_version: version } });
+  if (r && r.ok) {
+    return { status: 202, body: { ok: true, version, message: `Release of ${version} started. GitHub moves the label in a minute or two; other projects are offered it from then on.` } };
+  }
+  const why = !r ? 'no answer'
+    : r.code === 'UNCONFIGURED' ? 'this server has no GitHub credential'
+      : r.code === 'REFUSED' && r.status === 403 ? "GitHub refused: the server's GitHub App needs the Actions: write permission"
+        : r.code === 'REFUSED' && r.status === 404 ? 'GitHub could not find publish.yml, or the App cannot see this repository'
+          : r.code === 'REFUSED' ? `GitHub refused the request (${r.status})`
+            : r.code === 'UNREACHABLE' ? 'GitHub could not be reached'
+              : r.code;
+  return { status: 502, body: { error: { code: 'dispatch_failed', message: `Nothing was released: ${why}.` } } };
+}
+
+module.exports = { releaseCandidates, readReleaseLedger, requestRelease, WORKFLOW };

package/modules/npm-release/routes/release.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// modules/npm-release/routes/release.js — POST /npm-release/release, the deploy page's Release
+// button (task 1004298, ADR 0361). Body: { version }.
+//
+// It does not move anything itself. It asks GitHub to run publish.yml's release job, which checks
+// the same rule again and moves the registry's `latest` label — the version every project other
+// than the platform hall is offered. So the npm credential never leaves GitHub.
+//
+// GATED LIKE THE PAGE (`core.pin.move`), as an atom: the deploy page is served only to holders of
+// it, and a button wider than its page would be a door nobody sees. Never requireRank —
+// tests/government_require_permission.mjs fails the build on one in a modules/*/routes gate.
+//
+// Only the core's page releases: publish.yml publishes @bongos/core, and another package's
+// deploy page has no workflow here to run.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { requestRelease } = require('../release');
+
+const log = api.logger('npm-release');
+const CORE_PACKAGE = '@bongos/core';
+
+// The kernel validator checks presence, type and length; the x.y.z shape is checked by hand below.
+const releaseSchema = { version: { type: 'string', required: true, maxLength: 32 } };
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+module.exports = function buildNpmReleaseReleaseRouter({
+  pkg = () => process.env.NPM_RELEASE_PACKAGE || CORE_PACKAGE,
+  readRegistry = () => api.readPackageRegistry({ pkg: CORE_PACKAGE, haveNotesFor: () => true }),
+  port = () => api.resolveOptional && api.resolveOptional('lifecycle.workflowDispatch'),
+} = {}) {
+  const router = express.Router();
+
+  router.post(
+    '/npm-release/release',
+    api.requireBuilder,
+    api.requirePermission('core.pin.move'),
+    async (req, res) => {
+      if (api.validateOrRespond(req, res, releaseSchema, { strict: true })) return undefined;
+      if (!VERSION_RE.test(req.body.version)) {
+        return res.status(400).json({ error: { code: 'validation_failed', message: 'version must be x.y.z', details: [{ field: 'version', reason: 'bad_format' }] } });
+      }
+      if (pkg() !== CORE_PACKAGE) {
+        return res.status(409).json({ error: { code: 'not_the_core', message: 'Release runs only on the deploy page of the package this repository publishes (@bongos/core).' } });
+      }
+      const version = req.body.version;
+      try {
+        const { registry } = await readRegistry();
+        const p = port();
+        const dispatch = p && typeof p.dispatchWorkflow === 'function' ? (args) => p.dispatchWorkflow(args) : null;
+        const r = await requestRelease({ version, registry, dispatch });
+        const who = req.builder && req.builder.id;
+        if (r.status === 202) log.info(`release of core ${version} requested by builder ${who}`);
+        else log.warn(`release of core ${version} by builder ${who} not started: ${(r.body.error && r.body.error.code) || 'noop'}`);
+        return res.status(r.status).json(r.body);
+      } catch (e) {
+        log.error(`npm-release release failed: ${e && e.message}`);
+        return res.status(500).json({ error: { code: 'release_failed', message: 'Nothing was released: the request failed on this server.' } });
+      }
+    },
+  );
+
+  return router;
+};

package/modules/npm-release/work.js

@@ -30,6 +30,7 @@
 const fs = require('node:fs');
 const path = require('node:path');
 const api = require('../../src/module-api');
+const { releaseCandidates, readReleaseLedger } = require('./release');
 
 // The package this server runs — the one whose "live" version is this process's own core.
 // Any other package has no "live on this hall" stage: nothing here runs it.
@@ -292,6 +293,18 @@ async function readVersions({ pkg, live, installedNotes, get, now, store }) {
   return { liveVersion, registry, versions, source, notesError, coversTo, published, released };
 }
 
+// The Release section's reading. Fail-soft like the ledger it reads: an unreadable ledger still
+// lists the candidates, with no evidence and the reason, rather than hiding the button.
+async function releaseReading({ pool, registry, released, live, now }) {
+  if (!registry.ok) return { ok: false, error: registry.error || 'the registry could not be read', candidates: [] };
+  const ledger = await readReleaseLedger(pool);
+  return {
+    ok: true,
+    ledger_error: ledger.ok ? null : `this hall's upgrade ledger could not be read (${ledger.error})`,
+    candidates: releaseCandidates({ rows: ledger.rows, versions: registry.versions, released, live, now }),
+  };
+}
+
 async function readWork({
   pool, pkg = configuredPackage(), live, days, before, limit,
   installedNotes = readInstalledNotes, get, now, store,
@@ -332,6 +345,9 @@ async function readWork({
     // Only the core's page has a "this hall" to have upgraded: another package is not what this
     // server runs.
     upgrades: isCore ? await recentUpgrades(pool) : null,
+    // THE RELEASE BUTTON'S EVIDENCE (task 1004298): each version this hall runs that is not yet
+    // released, with how long it has run here and whether a move to it was ever rolled back.
+    release: isCore ? await releaseReading({ pool, registry, released, live: liveVersion, now: at }) : null,
     waiting: isCore && registry.ok ? waitingHere({ live: liveVersion, versions: registry.versions, published, now: at }) : null,
   };
 }

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.79",
+  "version": "1.20.80",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.20.79",
+      "version": "1.20.80",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.20.79",
+  "version": "1.20.80",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -8615,5 +8615,15 @@
       "id": "1004484",
       "text": "New projects no longer have their 'start' command pointing at the Bongos hall, so when an owner later connects Render with the usual 'npm start', it runs their app instead of a broken second copy of the hall."
     }
+  ],
+  "1.20.80": [
+    {
+      "id": "1004298",
+      "text": "New versions can now run on Bongos first and reach other projects only when the owner presses Release on the deploy page, which shows how long each version has run on Bongos and whether it was ever rolled back. Switched off un"
+    },
+    {
+      "id": "1003907",
+      "text": "Autobongos has now been proven against the live project: it shipped work by itself with nobody watching, refused every kind of work it is not allowed to touch, and recovered from restarts and network failures on its own. The o"
+    }
   ]
 }

package/scripts/gds/provision-core-upgrade.js

@@ -166,6 +166,34 @@ function instanceChannel(inst, channelMod) {
   return channelMod.normalizeChannel(inst && inst.update_channel != null ? inst.update_channel : channelMod.DEFAULT_CHANNEL);
 }
 
+// The versions this project may be moved to: the published ones its FOLLOW admits (task 1004298,
+// ADR 0361). The platform hall (control-plane) takes every candidate; every other project only what
+// has been released, and NOTHING when the registry cannot say which version that is — a project that
+// follows releases is never moved on a guess. A channel module without the follow (an old core
+// resolved at drain time) offers the whole list, which is what every version meant before candidates.
+//
+// The released label is one fact about the registry, the same for every project in a pass, and
+// reading it is a blocking `npm view`. So it is read once per channel module per RELEASE_TAGS_TTL_MS
+// and shared: a pass over N projects costs one extra subprocess, not N. A failed read is not kept.
+const RELEASE_TAGS_TTL_MS = 60 * 1000;
+const releaseTagsMemo = new WeakMap();
+function releaseTagsFor(channelMod, instanceDir, now = Date.now()) {
+  const hit = releaseTagsMemo.get(channelMod);
+  if (hit && now - hit.at < RELEASE_TAGS_TTL_MS) return hit.tags;
+  const tags = channelMod.readReleaseTags({ cwd: instanceDir });
+  if (tags && tags.ok) releaseTagsMemo.set(channelMod, { at: now, tags });
+  return tags;
+}
+
+function offeredVersions(channelMod, inst, instanceDir) {
+  const listed = channelMod.listAvailableVersions({ cwd: instanceDir });
+  if (!listed || !listed.ok || typeof channelMod.followForShape !== 'function') return listed;
+  if (channelMod.followForShape(inst && inst.hosting_shape) === 'candidates') return listed;
+  const tags = releaseTagsFor(channelMod, instanceDir);
+  if (!tags.ok) return { ok: false, error: `could not read which version is released (${tags.error})`, versions: [] };
+  return { ok: true, versions: channelMod.versionsForFollow({ follow: 'released', available: listed.versions, released: tags.released }) };
+}
+
 // A classified refusal (task 1004446): the drain loop stores `failure` beside last_error,
 // so the rest of the self-heal chain acts on a class, not on a sentence. PURE.
 function failed(reason, error, extra = {}) {
@@ -246,7 +274,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
   // pointed at nothing. A row from before the column (undefined) still normalises to that
   // default, so an old runner schema reads exactly as it always did.
   const channel = instanceChannel(inst, channelMod);
-  const listed = channelMod.listAvailableVersions({ cwd: instanceDir });
+  const listed = offeredVersions(channelMod, inst, instanceDir);
   const available = (listed && listed.versions) || [];
   const fault = targetFault(to, available, installed, channel, channelMod.channelAllows);
   if (fault) return failed(outcome.runnerReason(fault), fault);
@@ -1013,7 +1041,7 @@ async function snapshotCoreVersions(inst, deps) {
     const body = probe && !probe.softFailed ? (probe.stdout || '') : null;
     const served = parseServedVersion(body);
     const schemaPending = parseSchemaPending(body);
-    const listed = channelMod.listAvailableVersions({ cwd: instanceDir });
+    const listed = offeredVersions(channelMod, inst, instanceDir);
     const available = (listed && listed.versions) || [];
     // What the channel would take FROM the version the box is actually on. Resolving it
     // here rather than in the browser is what keeps the button's promise and the

package/scripts/gds/release-core.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+'use strict';
+// scripts/gds/release-core.js — may this version of @bongos/core be RELEASED? (task 1004298, ADR 0361)
+//
+// Merges publish as candidates (under the `next` label). A version reaches other projects only when
+// the owner presses Release on /deploy, which runs publish.yml's release job, which asks this script
+// and then moves the registry's `latest` label. Every consumer that offers a version to a project
+// other than the platform hall reads `latest` (update-channel.js versionsForFollow), so this label IS
+// the release.
+//
+// WHY A SCRIPT AND NOT A SHELL STEP. The rule has four ways to say no, and a shell `if` chain inside
+// a workflow file is the one place nothing can test it. The decision is pure and unit-tested
+// (tests/release_core.mjs); the workflow only runs it and acts on `go`.
+//
+// THE RULE:
+//   - the version must be a plain x.y.z (it is interpolated into an npm command line);
+//   - it must be PUBLISHED — Release labels a version, it never builds one;
+//   - it must be newer than the current release. Releasing an OLDER version would move every
+//     project's offer backwards, which is a rollback for everyone, not a release; that is a
+//     different act and needs a person at a terminal, not a button.
+//   - releasing the version already released is a no-op, not an error — a double press is harmless.
+//
+// Usage (in publish.yml's release job):
+//   node scripts/gds/release-core.js --version 1.20.80
+// Prints the decision; writes go=true|false to $GITHUB_OUTPUT when set. Exit 0 for go and no-op,
+// 1 for a refusal.
+
+const fs = require('node:fs');
+const { spawnSync } = require('node:child_process');
+const { CORE_PKG, parseSemver, compareSemver, isStable } = require('./update-channel.js');
+
+const VERSION_RE = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+
+/**
+ * PURE. `versions`: every published version. `latest`: the version the registry labels `latest`
+ * now, or null. Returns { go, noop, reason }.
+ */
+function releaseDecision({ version, versions, latest } = {}) {
+  const v = String(version == null ? '' : version).trim();
+  if (!VERSION_RE.test(v)) return { go: false, noop: false, reason: `"${v}" is not a version (x.y.z)` };
+  const list = Array.isArray(versions) ? versions : [];
+  if (!list.includes(v)) return { go: false, noop: false, reason: `${v} is not published — Release labels a published version, it never builds one` };
+  if (!isStable(v)) return { go: false, noop: false, reason: `${v} is a prerelease` };
+  if (latest && parseSemver(latest)) {
+    const c = compareSemver(v, latest);
+    if (c === 0) return { go: false, noop: true, reason: `${v} is already the release` };
+    if (c < 0) return { go: false, noop: false, reason: `${v} is older than the current release ${latest} — releasing it would move every project backwards` };
+  }
+  return { go: true, noop: false, reason: latest ? `release ${v} (was ${latest})` : `release ${v} (no release yet)` };
+}
+
+function readRegistry({ pkg = CORE_PKG, run = spawnSync } = {}) {
+  const res = run('npm', ['view', pkg, 'versions', 'dist-tags', '--json'], { encoding: 'utf8', timeout: 60000 });
+  if (!res || res.status !== 0) return { ok: false, error: String((res && res.stderr) || 'npm view failed').trim().split('\n')[0] };
+  try {
+    const doc = JSON.parse(String(res.stdout || '{}'));
+    const versions = Array.isArray(doc.versions) ? doc.versions : (typeof doc.versions === 'string' ? [doc.versions] : []);
+    const tags = doc['dist-tags'] || {};
+    return { ok: true, versions, latest: typeof tags.latest === 'string' ? tags.latest : null };
+  } catch (e) {
+    return { ok: false, error: `unparseable npm output: ${e.message}` };
+  }
+}
+
+function main(argv = process.argv.slice(2), { env = process.env, read = readRegistry, log = console.log, err = console.error } = {}) {
+  const i = argv.indexOf('--version');
+  const version = i >= 0 ? argv[i + 1] : '';
+  const out = (go) => { if (env.GITHUB_OUTPUT) fs.appendFileSync(env.GITHUB_OUTPUT, `go=${go}\n`); };
+  const reg = read();
+  if (!reg.ok) { err(`release-core: could not read the registry (${reg.error})`); out(false); return 1; }
+  const d = releaseDecision({ version, versions: reg.versions, latest: reg.latest });
+  out(d.go);
+  if (d.go || d.noop) { log(`release-core: ${d.reason}`); return 0; }
+  err(`release-core: refused — ${d.reason}`);
+  return 1;
+}
+
+if (require.main === module) process.exit(main());
+
+module.exports = { releaseDecision, main };

package/scripts/gds/update-channel.js

@@ -23,9 +23,9 @@
 //                has released to other projects. DEFAULT, for every project.
 //   candidates — every published version, the moment it is published. The platform's own hall, and
 //                only it: Bongos runs each version before anyone else is offered it.
-// The channel bounds how FAR a jump may go; the follow bounds which versions exist to jump to. Until
-// candidates publish under their own label (task 1004298), `latest` is the newest version and the two
-// follows pick the same target — the axis exists first so that the split changes nothing for Bongos.
+// The channel bounds how FAR a jump may go; the follow bounds which versions exist to jump to. Once
+// merges publish as candidates (task 1004298, ADR 0361), `latest` moves only when the owner presses
+// Release, so the two follows part: the platform hall takes each candidate, everyone else the release.
 //
 // WHY the registry as the source (not vendored tarballs): a subscription needs a LIVE source of
 // truth for "what's the newest published core?" — that's `npm view @bongos/core versions` against the
@@ -139,6 +139,14 @@ function versionsForFollow({ follow, available, released } = {}) {
   return list.filter((v) => compareSemver(v, released) <= 0);
 }
 
+// The follow a provisioned project takes, from its hosting shape (task 1004298, ADR 0361). The
+// control-plane row IS the platform's own hall, the one project that runs every candidate; every other
+// shape follows releases. Derived, not stored: there is exactly one platform hall, and a column an
+// operator could set on a tenant would be one more way to hand a project an unreleased version.
+function followForShape(hostingShape) {
+  return hostingShape === 'control-plane' ? 'candidates' : DEFAULT_FOLLOW;
+}
+
 // Would `channel` permit an unattended jump from `installed` to `candidate`? True only when candidate
 // is a STABLE release strictly newer than installed AND within the channel's blast radius. Any invalid
 // input, an unknown installed version, a prerelease candidate, or a major bump ⇒ false (fail-closed).
@@ -463,6 +471,7 @@ module.exports = {
   normalizeFollow,
   versionsForFollow,
   readReleaseTags,
+  followForShape,
   SUBSCRIPTIONS_REL,
   parseSemver,
   isStable,