@bongos/core 1.19.1038 → 1.19.1040

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

@@ -0,0 +1,46 @@
+'use strict';
+
+// modules/npm-release/routes/work.js — GET /npm-release/work, the deploy page's
+// "where is my work?" reading (task 1002622). See ../work.js for what it answers.
+//
+// GATED LIKE THE PAGE IT FEEDS. /deploy is served only to holders of `core.pin.move`
+// (serve-internal.js DEPLOY_PAGE_RE), and this answer carries the same disclosure the
+// door's own preview does — the exact core this hall runs and how far behind the
+// newest it is (ADR 0043's reason for gating that preview). A read no wider than the
+// page is also what keeps the page from ever offering more than its API will answer.
+// An atom, not requireRank: tests/government_require_permission.mjs fails the build on
+// a new requireRank in a modules/*/routes gate (BV1.R105 / ADR 0151).
+//
+// READ-ONLY. Nothing here writes, queues or moves anything; the Release button is a
+// separate route with its own gate.
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { readWork } = require('../work');
+
+const log = api.logger('npm-release');
+
+module.exports = function buildNpmReleaseWorkRouter({ read = readWork } = {}) {
+  const router = express.Router();
+
+  // Query: days (ledger window, default 14, max 60), before + limit (history paging).
+  // Read by hand rather than through validateOrRespond: every field is optional and
+  // clamped, so there is nothing to refuse.
+  router.get(
+    '/npm-release/work',
+    api.requireBuilder,
+    api.requirePermission('core.pin.move'),
+    async (req, res) => {
+      try {
+        const q = req.query || {};
+        const before = typeof q.before === 'string' ? q.before : undefined;
+        res.json(await read({ pool: api.pool, days: q.days, before, limit: q.limit }));
+      } catch (e) {
+        log.error(`npm-release work read failed: ${e && e.message}`);
+        res.status(500).json({ error: { code: 'work_read_failed', message: 'Could not read where the work is right now.' } });
+      }
+    },
+  );
+
+  return router;
+};

package/modules/npm-release/work.js

@@ -0,0 +1,252 @@
+'use strict';
+
+// modules/npm-release/work.js — "where is my work?", answered for the deploy page (task 1002622).
+//
+// THE COMPLAINT THIS EXISTS FOR. The owner, 2026-09-26, over a /deploy that read "Serving
+// 1.19.1033 … Core 1.19.1039 is published": "I did so many tasks and changes yesterday and
+// it's not showing anything that's been done." Fifteen tasks marked shipped sat between those
+// two numbers, and the page named none of them. A version number is the least useful thing a
+// deploy page can show; the work is the thing its reader did.
+//
+// SO EVERY RECENT TASK IS PLACED IN THE STAGE IT HAS ACTUALLY REACHED, in the order work
+// travels:
+//   not_merged       the ledger says done (completed / confirmed), the code is not on main
+//   unversioned      merged after the newest version the notes reach was published
+//   not_live         in a version newer than the one this hall runs
+//   live_unreleased  running here, but not yet what other projects are offered
+//   released         running here and offered to other projects
+//   no_version       shipped, but no version names it — a ledger-only ship (a scope edit, a
+//                    verify task) or a merge whose note could not be tied to a task
+//
+// THE JOIN. A version's work comes from the release notes the package was packed with, where
+// each merge that carried `task <id>: <summary>` is `{ id, text }`. A hand-landed merge names
+// no id, so an entry without one is matched on its text against the task's own ship summary —
+// the same sentence ship.js wrote into the merge. Nothing is inferred from the changelog,
+// whose CI lines ("carrier for merges landed since …") name no work at all.
+//
+// THE PAGE KNOWS NOTHING (deploy.js's rule, kept). Every version and verdict here is a reading
+// with its source and time; a reading that failed is reported as failed, never as empty.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const api = require('../../src/module-api');
+const { readRegistry, compareVersions } = require('./registry');
+
+// 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.
+const CORE_PACKAGE = '@bongos/core';
+const VERSION_RE = /^\d+\.\d+\.\d+$/;
+const TEXT_MAX = 400;
+const DEFAULT_DAYS = 14;
+const MAX_DAYS = 60;
+const DEFAULT_LIMIT = 30;
+const MAX_LIMIT = 100;
+// The core carries its notes at its package root: <root>/release-notes.json, beside
+// package.json. From modules/npm-release/ that is two levels up.
+const INSTALLED_NOTES = path.join(__dirname, '..', '..', 'release-notes.json');
+
+/** The package this project publishes. Config, not code: another project names its own. */
+function configuredPackage(env = process.env) {
+  const v = String(env.NPM_RELEASE_PACKAGE || '').trim();
+  return v || CORE_PACKAGE;
+}
+
+function readInstalledNotes() {
+  try { return JSON.parse(fs.readFileSync(INSTALLED_NOTES, 'utf8')); }
+  catch { return null; }
+}
+
+function boundText(text) {
+  const t = String(text || '').trim();
+  return t.length > TEXT_MAX ? `${t.slice(0, TEXT_MAX - 1)}…` : t;
+}
+
+/** A notes file's versions, oldest first, each entry re-checked (it may have come off the network). */
+function versionsIn(notes) {
+  if (!notes || typeof notes !== 'object' || Array.isArray(notes)) return [];
+  return Object.keys(notes)
+    .filter((v) => VERSION_RE.test(v) && Array.isArray(notes[v]))
+    .sort(compareVersions)
+    .map((v) => ({
+      version: v,
+      entries: notes[v]
+        .filter((e) => e && typeof e.text === 'string' && e.text.trim())
+        .map((e) => (/^\d+$/.test(String(e.id || '')) ? { id: String(e.id), text: boundText(e.text) } : { text: boundText(e.text) })),
+    }));
+}
+
+/**
+ * Where each task stands. PURE — every input injected.
+ *
+ * `tasks`: ledger rows `{ id, title, status, at, builder, summary }`.
+ * `versions`: `versionsIn` output. `live` / `released`: versions or null. `coveredAt`: when
+ * the newest version the notes reach was published (ISO) or null when unknown.
+ */
+function placeTasks({ tasks, versions, live, released, coveredAt }) {
+  const byId = new Map();
+  const byText = new Map();
+  for (const { version, entries } of versions) {
+    for (const e of entries) {
+      if (e.id && !byId.has(e.id)) byId.set(e.id, version);
+      if (!e.id && !byText.has(e.text)) byText.set(e.text, version);
+    }
+  }
+  const covered = coveredAt ? Date.parse(coveredAt) : NaN;
+  const stages = { not_merged: [], unversioned: [], not_live: [], live_unreleased: [], released: [], no_version: [] };
+  for (const t of tasks) {
+    const row = { id: String(t.id), title: t.title, status: t.status, builder: t.builder || null, at: t.at };
+    if (t.status !== 'shipped') { stages.not_merged.push(row); continue; }
+    const version = byId.get(row.id) || (t.summary ? byText.get(boundText(t.summary)) : undefined);
+    if (!version) {
+      // Merged after the notes' newest version went out: it is waiting for the next one.
+      // Before it (or with no way to tell): no version names it.
+      const at = Date.parse(t.at);
+      if (Number.isFinite(covered) && Number.isFinite(at) && at > covered) stages.unversioned.push(row);
+      else stages.no_version.push(row);
+      continue;
+    }
+    row.version = version;
+    const offered = released ? compareVersions(version, released) <= 0 : null;
+    if (live && compareVersions(version, live) > 0) {
+      // Offered to other projects before this hall ran it — the order the Release step
+      // exists to prevent. Said, not hidden.
+      if (offered) row.offered = true;
+      stages.not_live.push(row);
+    } else if (offered === false) stages.live_unreleased.push(row);
+    else stages.released.push(row);
+  }
+  return stages;
+}
+
+/** The version history, newest first, from `before` (exclusive) down, `limit` long. PURE. */
+function history({ versions, published, live, released, newest, before, limit, titles }) {
+  const known = new Map(versions.map((v) => [v.version, v.entries]));
+  // Versions the registry lists but the notes do not reach are shown as unread, never
+  // dropped: a history with a silent hole in it reads as "nothing happened there".
+  const all = new Set(versions.map((v) => v.version));
+  for (const v of Object.keys(published || {})) if (!newest || compareVersions(v, newest) <= 0) all.add(v);
+  let list = [...all].sort(compareVersions).reverse();
+  if (before && VERSION_RE.test(before)) list = list.filter((v) => compareVersions(v, before) < 0);
+  const page = list.slice(0, limit);
+  return {
+    more: list.length > page.length,
+    versions: page.map((v) => ({
+      version: v,
+      published_at: (published && published[v]) || null,
+      live: live === v,
+      released: released === v,
+      entries: known.has(v)
+        ? known.get(v).map((e) => (e.id ? { id: e.id, title: titles.get(e.id) || null, text: e.text } : { text: e.text }))
+        : null,
+    })),
+  };
+}
+
+async function recentTasks(pool, days) {
+  // Who did it: the shipper once shipped, the last claimant before that.
+  const { rows } = await pool.query(
+    `SELECT t.id, t.title, t.status, t.value_summary,
+            COALESCE(t.shipped_at, t.updated_at) AS at,
+            COALESCE(sb.display_name, sb.github_login, cb.display_name, cb.github_login) AS builder
+       FROM tasks t
+       LEFT JOIN builders sb ON sb.id = t.shipped_by
+       LEFT JOIN LATERAL (
+         SELECT c.builder_id FROM claims c WHERE c.task_id = t.id ORDER BY c.claimed_at DESC LIMIT 1
+       ) lc ON true
+       LEFT JOIN builders cb ON cb.id = lc.builder_id
+      WHERE t.status IN ('completed', 'confirmed', 'shipped')
+        AND COALESCE(t.shipped_at, t.updated_at) >= now() - make_interval(days => $1::int)
+      ORDER BY COALESCE(t.shipped_at, t.updated_at) DESC
+      LIMIT 500`,
+    [days],
+  );
+  return rows.map((r) => ({
+    id: String(r.id),
+    title: r.title,
+    status: r.status,
+    summary: r.value_summary || null,
+    builder: r.builder || null,
+    at: r.at instanceof Date ? r.at.toISOString() : r.at,
+  }));
+}
+
+async function taskTitles(pool, ids) {
+  if (!ids.length) return new Map();
+  const { rows } = await pool.query('SELECT id, title FROM tasks WHERE id = ANY($1::bigint[])', [ids]);
+  return new Map(rows.map((r) => [String(r.id), r.title]));
+}
+
+function clampInt(v, dflt, max) {
+  const n = Number.parseInt(v, 10);
+  return Number.isInteger(n) && n > 0 ? Math.min(n, max) : dflt;
+}
+
+/**
+ * The deploy page's whole reading, in one call — the route's only dependency.
+ *
+ * `days` bounds the ledger window, `before` + `limit` page the version history. `get`,
+ * `now`, `store` and `installedNotes` are the seams tests drive; `live` defaults to this
+ * process's own core version when the package is the core.
+ */
+async function readWork({
+  pool, pkg = configuredPackage(), live, days, before, limit,
+  installedNotes = readInstalledNotes, get, now, store,
+} = {}) {
+  const windowDays = clampInt(days, DEFAULT_DAYS, MAX_DAYS);
+  const pageLimit = clampInt(limit, DEFAULT_LIMIT, MAX_LIMIT);
+  const running = live !== undefined ? live : (pkg === CORE_PACKAGE ? api.CORE_VERSION : null);
+  const liveVersion = VERSION_RE.test(String(running || '')) ? running : null;
+
+  const local = pkg === CORE_PACKAGE ? installedNotes() : null;
+  const localVersions = versionsIn(local);
+  const localTop = localVersions.length ? localVersions[localVersions.length - 1].version : null;
+
+  const { registry, notes } = await readRegistry({
+    pkg, get, now, store,
+    haveNotesFor: (v) => !!localTop && compareVersions(localTop, v) >= 0,
+  });
+
+  // The newest notes win; the installed copy stands in when they could not be read.
+  let versions = localVersions;
+  let source = localTop ? { from: 'installed', version: localTop } : null;
+  let notesError = null;
+  if (notes.ok) {
+    versions = versionsIn(notes.notes);
+    source = { from: 'package', version: notes.version };
+  } else if (!notes.skipped) {
+    notesError = notes.error || 'the release notes could not be read';
+  }
+  const coversTo = versions.length ? versions[versions.length - 1].version : null;
+  const published = registry.ok ? registry.published : {};
+  const released = registry.ok ? registry.latest : null;
+
+  const tasks = await recentTasks(pool, windowDays);
+  const stages = placeTasks({ tasks, versions, live: liveVersion, released, coveredAt: coversTo ? published[coversTo] || null : null });
+
+  const known = new Map(tasks.map((t) => [t.id, t.title]));
+  const hist = history({
+    versions, published, live: liveVersion, released,
+    newest: registry.ok ? registry.newest : coversTo,
+    before, limit: pageLimit, titles: known,
+  });
+  const missing = [...new Set(hist.versions.flatMap((v) => (v.entries || []).filter((e) => e.id && !e.title).map((e) => e.id)))];
+  if (missing.length) {
+    const more = await taskTitles(pool, missing);
+    for (const v of hist.versions) for (const e of v.entries || []) if (e.id && !e.title) e.title = more.get(e.id) || null;
+  }
+
+  return {
+    package: pkg,
+    checked_at: new Date(now ? now() : Date.now()).toISOString(),
+    live: liveVersion,
+    released,
+    newest: registry.ok ? registry.newest : null,
+    registry: registry.ok ? { ok: true } : { ok: false, error: registry.error },
+    notes: { source, covers_to: coversTo, error: notesError },
+    window_days: windowDays,
+    stages,
+    history: hist,
+  };
+}
+
+module.exports = { readWork };

package/modules/provisioning/starter-bundles.js

@@ -68,8 +68,12 @@ const ALWAYS_ON_CORE = Object.freeze([
 // provider ("enabled ONLY on the hub instance") and `provisioning` is the surface
 // that stands other instances up — a project created THROUGH the hub is a
 // consumer of both, never a second copy of them. Named so the integrity test can
-// refuse them by construction rather than by anyone remembering.
-const HUB_ONLY_MODULES = Object.freeze(['platform-identity', 'provisioning']);
+// refuse them by construction rather than by anyone remembering. `npm-release` is the
+// deploy page of the one project that PUBLISHES the core (task 1002622): every project
+// the hub creates receives those releases, so none is offered the publisher's page. It
+// is package-agnostic by construction, so offering it to a project that publishes its
+// own npm package is a later, deliberate removal from this list — with picker copy.
+const HUB_ONLY_MODULES = Object.freeze(['platform-identity', 'provisioning', 'npm-release']);
 
 // Modules that were once offered and are being WITHDRAWN. A retired key is still
 // a module on disk — its manifest, routes and tables are deleted by later tasks —

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.1038",
+  "version": "1.19.1040",
   "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

@@ -7509,9 +7509,33 @@
     }
   ],
   "1.19.1038": [
+    {
+      "id": "1004289",
+      "text": "When the code host refuses to run the automatic tests at all, for example because the account's allowance ran out, the shipping tool now says so plainly and names the owner's fix, instead of telling the builder to fix code tha"
+    },
     {
       "id": "1002840",
       "text": "The grader can now call AI models from other companies through one plug-in point, ready for a second-opinion reviewer; nothing changes today — it still uses only Claude and spends nothing new."
     }
+  ],
+  "1.19.1039": [
+    {
+      "id": "1004290",
+      "text": "A new release of the core is now published only after the check that it can set up a brand-new empty database has passed, so a release that cannot install cleanly can no longer reach projects."
+    }
+  ],
+  "1.19.1040": [
+    {
+      "id": "1002622",
+      "text": "The Deploy page now lists every recently finished task by name and shows how far each one has got — not merged yet, published, running on Bongos, or released — plus what each version carried."
+    },
+    {
+      "id": "1004282",
+      "text": "Wrote up tonight's work on accounts and community: 12 changes finished, the site upgraded, and your page-placement decisions turned into tasks. New code is paused until the GitHub build budget resets next month."
+    },
+    {
+      "id": "1003368",
+      "text": "Closed a security hole where a builder's branch could choose the program the server runs while auto-resolving merge conflicts; the server now always uses its own trusted copy."
+    }
   ]
 }

package/scripts/gds/exec-path-guard.js

@@ -64,7 +64,7 @@ const STATIC_ROOTS = new Set([
 // brittle — a line shift re-opens the review rather than carrying a stale approval.
 const EXEMPTIONS = [
   {
-    at: 'modules/lifecycle/conflict-resolve.js:382',
+    at: 'modules/lifecycle/conflict-resolve.js:390',
     why: 'THE site this check was written for (audit ref B1), and the one place a runtime path is '
        + 'REQUIRED rather than tolerated. Each generator derives its repo root from its own '
        + '__dirname, so running the SERVER\'s copy would regenerate the deploy tree instead of the '

package/scripts/gds/install-git-hooks.js

@@ -49,14 +49,30 @@ const MERGE_DRIVER_NAME = 'otb-regen';
 //   - `.name` alone is the fatal state above.
 // So writing `.driver` FIRST makes the intermediate state safe, and removing the whole
 // section on failure makes even a mid-write abort leave no trace.
-function registerMergeDriver(root, { run = execFileSync } = {}) {
+//
+// `driverScript` (task 1003368, audit B2) pins the command to an ABSOLUTE path. The default
+// is the RELATIVE `scripts/gds/git-merge-regen.js`, which git resolves against the merge's
+// cwd — the checked-out tree — so on a clone of a builder's branch it names the BRANCH's copy
+// of the script. The server's conflict resolver passes its own checkout's copy so the command
+// git runs is never one the branch could have written. Only the server-side caller may pass
+// it; a builder's own clone keeps the relative form, which is what they want to run.
+function mergeDriverCommand(driverScript) {
+  if (!driverScript) return 'node scripts/gds/git-merge-regen.js %O %A %B %P';
+  // Forward slashes + double quotes: git hands this to `sh -c`, and a path with spaces or a
+  // Windows backslash would otherwise split or be eaten as an escape.
+  const abs = path.resolve(driverScript).replace(/\\/g, '/');
+  if (/["$`]/.test(abs)) throw new Error(`unsafe merge driver path: ${abs}`);
+  return `node "${abs}" %O %A %B %P`;
+}
+
+function registerMergeDriver(root, { run = execFileSync, driverScript } = {}) {
   // execFileSync (arg array, no shell) so the literal %O/%A/%B/%P placeholders and
   // the spaces in the command survive verbatim on every platform (a shell would
   // mangle %VARS on Windows cmd).
   try {
     // .driver FIRST — a section carrying only .driver is valid and works.
     run('git', ['config', `merge.${MERGE_DRIVER_NAME}.driver`,
-      'node scripts/gds/git-merge-regen.js %O %A %B %P'], { cwd: root, stdio: 'ignore' });
+      mergeDriverCommand(driverScript)], { cwd: root, stdio: 'ignore' });
     // .name SECOND — cosmetic (it is what `git config --list` shows); if this throws,
     // the section left behind is the safe driver-only one.
     run('git', ['config', `merge.${MERGE_DRIVER_NAME}.name`,

package/scripts/gds/plain-cards.js

@@ -169,6 +169,11 @@ const CARDS = Object.freeze({
     'An automatic test failed on your work, so it has not been added to the project.',
     'I will run that test here, fix what it found, and send the work again. Sending the same work again would fail the same way.',
     null, FAULT),
+  // task 1004289: the tests never ran at all (the account cannot run them right now).
+  ci_not_started: card(
+    'The automatic tests never ran on your work: the code host did not start them, because the account has run out of test time or has a payment problem. Nothing was tested, so nothing needs fixing.',
+    'I will not change the work. Once the owner restores the test time, I will start the tests again on the same work and it will be added on its own.',
+    'The project owner, to restore the account\'s test time on the code host.', FAULT),
   non_required_check_failing: card(
     'An optional automatic test failed on your work.',
     'I will look at what it found. It does not stop the work being added, but it is usually worth fixing.',

package/scripts/gds/publish-integration-gate.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+// scripts/gds/publish-integration-gate.js — the publish lane waits for the integration
+// lane's verdict on the exact commit it is about to release (task 1004290).
+//
+// WHY. publish.yml fires on the `unit` workflow's success, and `unit` is DB-free by
+// design. The proof that the packaged core can set up an EMPTY database and serve a
+// DB-backed route — tests/consumer_layout_boot.mjs, task 1002863 — runs in the
+// `integration` workflow, on the same main push. Without this gate that result arrived
+// after the publish and gated nothing: a core that installs and boots but cannot migrate
+// its own database still reached npm, and from there the nightly tenant upgrade sweep.
+//
+// WHAT IT COSTS, MEASURED 2026-09-26 (not assumed). Both lanes start on the same push, and
+// integration is the SHORTER one: on the two commits right after task 1002863 landed,
+// integration took 247s and 245s against unit's 351s and 335s. So when unit's success fires
+// the publish, integration has usually already answered and this gate is a single API
+// read. It runs inside the existing publish job — no new job — and it polls only in the
+// rare case integration is still going. Over 299 main pushes (2026-09-20 → 26) integration
+// was green 254 times, cancelled 41 times (a newer merge superseded it) and red 3 times,
+// all three the Actions-budget outage of 2026-09-25 — so it is not a flaky lane that would
+// stall every release.
+//
+// THE VERDICTS (decideIntegrationGate, pure):
+//   go          the newest push-event run on this commit succeeded → publish
+//   wait        no run yet, or it is still going → poll
+//   superseded  it was cancelled — almost always a newer merge's run replacing it under
+//               integration.yml's cancel-in-progress group. Nothing is published; that
+//               newer merge fires its own publish, which asks about its own commit.
+//   red         anything else (failure, timed_out, startup_failure …) → refuse, loudly
+// Only PUSH-event runs count: the weekly scheduled run on main carries HEAD's sha but runs
+// only the parked-set ratchet, so its conclusion says nothing about this commit.
+//
+// OUTPUT: `go=true|false` to $GITHUB_OUTPUT. Exit 0 for go and superseded, 1 for red,
+// timeout or an unreadable API (a refusal that must be seen), 2 for bad arguments.
+//
+//   node scripts/gds/publish-integration-gate.js --sha <40-hex> --repo <owner/name>
+//        [--timeout-min 12] [--interval-s 20]      token: GH_TOKEN or GITHUB_TOKEN
+
+'use strict';
+
+const fs = require('node:fs');
+
+const WORKFLOW_FILE = 'integration.yml';
+const DEFAULT_TIMEOUT_MIN = 12; // inside publish.yml's 20-minute job, leaving room to pack + publish
+const DEFAULT_INTERVAL_S = 20;
+const SHA_RE = /^[0-9a-f]{40}$/;
+const REPO_RE = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+
+// decideIntegrationGate — PURE. `runs` is list-workflow-runs' `workflow_runs` for one
+// head sha and the push event. The newest run decides (a re-push of the same sha, or a
+// re-run, supersedes an older verdict).
+function decideIntegrationGate(runs) {
+  const list = Array.isArray(runs) ? runs.filter((r) => r && typeof r === 'object') : [];
+  if (!list.length) return { verdict: 'wait', run: null };
+  const newest = list.slice().sort((a, b) =>
+    (Number(b.run_number) || 0) - (Number(a.run_number) || 0)
+    || String(b.created_at || '').localeCompare(String(a.created_at || '')))[0];
+  if (newest.status !== 'completed') return { verdict: 'wait', run: newest };
+  if (newest.conclusion === 'success') return { verdict: 'go', run: newest };
+  if (newest.conclusion === 'cancelled') return { verdict: 'superseded', run: newest };
+  return { verdict: 'red', run: newest };
+}
+
+function runsUrl(repo, sha) {
+  return `https://api.github.com/repos/${repo}/actions/workflows/${WORKFLOW_FILE}/runs?head_sha=${sha}&event=push&per_page=20`;
+}
+
+// waitForIntegration — poll until the gate has a verdict or the time is up. A 401/403/404
+// is not something waiting fixes (a missing `actions: read`, a renamed workflow), so it
+// ends the wait at once as 'unreadable'. Any other failed read is retried. Everything that
+// touches the world is injectable for tests/publish_integration_gate.mjs.
+async function waitForIntegration({
+  sha, repo, token, timeoutMs, intervalMs,
+  fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now,
+}) {
+  const deadline = now() + timeoutMs;
+  let last = { verdict: 'wait', run: null, why: 'no read yet' };
+  for (;;) {
+    try {
+      const res = await fetchImpl(runsUrl(repo, sha), {
+        headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' },
+      });
+      if ([401, 403, 404].includes(res.status)) return { verdict: 'unreadable', run: null, why: `HTTP ${res.status}` };
+      if (res.ok) {
+        const body = await res.json();
+        last = { ...decideIntegrationGate(body && body.workflow_runs), why: null };
+        if (last.verdict !== 'wait') return last;
+      } else {
+        last = { ...last, why: `HTTP ${res.status}` };
+      }
+    } catch (e) {
+      last = { ...last, why: (e && e.message) || String(e) };
+    }
+    if (now() + intervalMs > deadline) return { verdict: 'timeout', run: last.run, why: last.why };
+    await sleep(intervalMs);
+  }
+}
+
+// The one line per outcome the Actions log shows, and what the rest of the lane reads.
+function reportLines(verdict, { sha, run, why, timeoutMin }) {
+  const short = String(sha).slice(0, 8);
+  const url = run && run.html_url ? ` ${run.html_url}` : '';
+  switch (verdict) {
+    case 'go':
+      return { go: true, code: 0, line: `integration is green on ${short}${url} — publishing.` };
+    case 'superseded':
+      return { go: false, code: 0, line: `::notice title=not published — integration was cancelled on ${short}::Usually a newer merge's run replaced it; that merge fires its own publish, which checks its own commit.${url}` };
+    case 'red':
+      return { go: false, code: 1, line: `::error title=not published — integration is red on ${short}::The integration lane (${run && run.conclusion}) runs the proof that the packaged core can migrate an empty database (task 1002863). A core that fails it must not reach npm. Fix main; the next merge publishes everything.${url}` };
+    case 'unreadable':
+      return { go: false, code: 1, line: `::error title=not published — cannot read the integration lane::${why}. publish.yml needs 'permissions: actions: read', and the workflow file must still be ${WORKFLOW_FILE}.` };
+    default:
+      return { go: false, code: 1, line: `::error title=not published — integration had no verdict on ${short} after ${timeoutMin} min::${why ? `Last read: ${why}. ` : ''}Re-run this workflow once integration finishes, or let the next merge publish.${url}` };
+  }
+}
+
+function argValue(argv, flag) {
+  const i = argv.indexOf(flag);
+  return i >= 0 && i + 1 < argv.length ? argv[i + 1] : null;
+}
+
+async function main(argv = process.argv.slice(2), env = process.env) {
+  const sha = String(argValue(argv, '--sha') || '').toLowerCase();
+  const repo = String(argValue(argv, '--repo') || env.GITHUB_REPOSITORY || '');
+  const token = env.GH_TOKEN || env.GITHUB_TOKEN || '';
+  const timeoutMin = Number(argValue(argv, '--timeout-min') || DEFAULT_TIMEOUT_MIN);
+  const intervalS = Number(argValue(argv, '--interval-s') || DEFAULT_INTERVAL_S);
+  if (!SHA_RE.test(sha) || !REPO_RE.test(repo) || !token || !(timeoutMin > 0) || !(intervalS > 0)) {
+    console.error('usage: publish-integration-gate.js --sha <40-hex> --repo <owner/name> [--timeout-min N] [--interval-s N]  (token: GH_TOKEN or GITHUB_TOKEN)');
+    return 2;
+  }
+  const result = await waitForIntegration({ sha, repo, token, timeoutMs: timeoutMin * 60000, intervalMs: intervalS * 1000 });
+  const out = reportLines(result.verdict, { sha, run: result.run, why: result.why, timeoutMin });
+  console.log(out.line);
+  if (env.GITHUB_OUTPUT) fs.appendFileSync(env.GITHUB_OUTPUT, `go=${out.go}\n`);
+  return out.code;
+}
+
+if (require.main === module) {
+  main().then((code) => { process.exitCode = code; }, (e) => { console.error(e); process.exitCode = 1; });
+}
+
+module.exports = { decideIntegrationGate, waitForIntegration, reportLines, main, WORKFLOW_FILE, runsUrl };

package/scripts/gds/publish-manifest.js

@@ -72,6 +72,7 @@ const PUBLISH_ALLOWLIST = [
   'modules/discord/',
   'modules/provisioning/',   // instance-hosting control plane — CORE like its sibling dev-box (same do-api/cf-tunnel toolchain, all core). Reclassified IN so the core CLI scripts/gds/provision.js resolves it from the core package post-split, not a MODULE_NOT_FOUND (task 2135). default:false — shipped ≠ enabled.
   'modules/agents/',         // the declarative agent registry + spawn seam (goal 1000038) — CORE: its own manifest declares maintenance.status 'core-maintained', and it consumes the core `grade` port, so a released core without it cannot run the MAS machinery the methodology describes. default:false — shipped is not enabled (ADR 0083), exactly like provisioning + platform-identity below. Omitted at module-creation time (tasks 1002485/1002486): the omission was invisible until tests/agents_spawn.mjs became the first PUBLISHABLE file to import it and the R89 boundary guard caught it (task 1002489).
+  'modules/npm-release/',    // the deploy page's "where is the work" + version history (task 1002622). default:false — on only in the hall that publishes the core. MUST be here: modules/hall-ui/ ships as one subtree, so a released core without this carries deploy.js's loader and the #nr-work mounts with no routes behind them — the copy-desk asymmetry above.
   'modules/platform-identity/', // hub identity provider (ADR 0141) — ships in core, enabled ONLY on the hub (cloudbongos.com). MUST be here or the hub's enabledModules() throws "unknown module" and provision.js's federation load MODULE_NOT_FOUNDs (task 1002235, same rationale as provisioning above). default:false — shipped ≠ enabled; a vanilla/self-hosted instance never turns it on.
   // --- neutral (customer-0) config starters + their schemas (the filled-in *.json twins are denied) ---
   'config/branding.neutral.json',