@bongos/core 1.19.989 → 1.19.990

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.989",
-  "core_contract": "1.19.989",
-  "source_commit": "e2ff7b827391116e3e99f4b850441ca7482a3466",
+  "core_version": "1.19.990",
+  "core_contract": "1.19.990",
+  "source_commit": "b1a0a6f54282f522323d1e84921384ce4af0d190",
   "source_ref": "HEAD",
-  "built_at": "2026-09-23T19:44:16.401Z",
+  "built_at": "2026-09-23T19:56:56.227Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 518,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2394,
+    "functional_verbatim": 2396,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2938,
-  "tree_sha256": "65dea20f4453b26ed36b673a7a34da0008c338d0f4307aa1b327f3171ce42cb0",
+  "file_count": 2940,
+  "tree_sha256": "2568c6298b1a5aa67172a39885d5bf19ef7a05679f3032125d57660ee881e2ca",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2152,7 +2152,7 @@
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "b227cab471090f0e961366e0299ad4ac7195c9123e46215f4af7b3bd7cf7713b"
+      "sha256": "8b1f2a53680ae8b68be5d54a82664413fa29186fb580825f5a1b0e3ce3677525"
     },
     {
       "path": "docs/architecture.md",
@@ -2712,7 +2712,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "b06d9ffcfde6e55a0997ffa926a671d0f53478d5e7c351b92374485e359cc0cd"
+      "sha256": "807ee161f37480d116b1e3c75835fcde8eb347dc994839a69c0f3aeaa43e273e"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2832,7 +2832,7 @@
     {
       "path": "docs/recipes/core-release-pipeline.md",
       "mode": "0000644",
-      "sha256": "53721b3314eab8f538aa7027862253abdbdd41be59f9dce75431c1b40ef80e63"
+      "sha256": "12e2fdc72d1bed7d524b50960dea3a67791b098b7dbafaff9c6f95cd356b185a"
     },
     {
       "path": "docs/recipes/failed-ship-recovery-proof.md",
@@ -2962,7 +2962,7 @@
     {
       "path": "docs/recipes/upgrading-the-core.md",
       "mode": "0000644",
-      "sha256": "0df57ea34114fb1ae81389458334b392d768fc83d9e82eb00fa917219189de87"
+      "sha256": "e035ebbda54d0d94f38bbcc9502689318c4f9bb2fe5bcca2592aa710dca5ffb0"
     },
     {
       "path": "docs/recipes/windows-builders.md",
@@ -6042,7 +6042,7 @@
     {
       "path": "modules/lifecycle/routes/artist-gate.js",
       "mode": "0000644",
-      "sha256": "6b7928201e9bb8c35691f388b1aa73c0986dd9d5e186796d8b087b7a1645ac96"
+      "sha256": "9b6990b00e071e2b47c20fc790f975db63563b700ffbd4a6b0c60dfd138f0def"
     },
     {
       "path": "modules/lifecycle/routes/claims.js",
@@ -8162,12 +8162,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "09936259916688c880c3c787419714a83a798ccf7fd09b50d7fe26d3d293e600"
+      "sha256": "47f81c7b7d52feec484d30c948a6f511be97d949d51008e3951536b6d5a16e4d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "126708cbc785a14f0cf42ef0a151889033a852f1a331e6ab73b0c75743f41856"
+      "sha256": "eb28fe24fd57a826eee9a4c24dae6980d2ba6cfd59f866bdf40b4ededb09bab0"
     },
     {
       "path": "public-docs/index.html",
@@ -9739,10 +9739,15 @@
       "mode": "0000644",
       "sha256": "6418f51f933eac634a7df854af1e3a6dbde25e152e3dca0ce8df7d37d19c1d0c"
     },
+    {
+      "path": "scripts/gds/upgrade-artist-gate.js",
+      "mode": "0000644",
+      "sha256": "caf07b70b066fe1388037ce1c622ea3aed82cbf43f67ffb918214159cbe4444e"
+    },
     {
       "path": "scripts/gds/upgrade.js",
       "mode": "0000644",
-      "sha256": "d736a08f303447e3889c478b0a22d6e9ae96e326f75bd57bead6199ffc23f1c5"
+      "sha256": "70a7de81b25a17cb7ab7e57f92577b6d977f89911b784f33df668b650fb208b0"
     },
     {
       "path": "scripts/gds/validate-design.js",
@@ -10202,7 +10207,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "5ed09f42ce4e04ca5f27bc3d4004ceab18bf604bd8a8fca72648afbf389b0935"
+      "sha256": "dcb76f459cc34113dd39ecd6229efe70abf82efc64da2c8c7ff35f514c8b17ec"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10507,7 +10512,7 @@
     {
       "path": "tests/artist_gate_route.mjs",
       "mode": "0000644",
-      "sha256": "616c19815b83f6796856ad6000eda4ce1c66eb526ecc4c1b901abdd9c49b4285"
+      "sha256": "3337ab686f2fa4bef95d0eabcf9b134a9b919d40480750e07a500b8007ae9659"
     },
     {
       "path": "tests/asset_version.mjs",
@@ -14549,6 +14554,11 @@
       "mode": "0000644",
       "sha256": "8bd1c116b5459b54a847208c01669159414fed17b3704d621e1dc5acfb00f255"
     },
+    {
+      "path": "tests/upgrade_artist_gate.mjs",
+      "mode": "0000644",
+      "sha256": "a9b5fadd7f829fd54a9d976d82832eb536e7d988c466647860b0257109feec50"
+    },
     {
       "path": "tests/upgrade_persist_pin.mjs",
       "mode": "0000644",

package/docs/api/openapi.json

@@ -1065,7 +1065,7 @@
           "artist-gate"
         ],
         "summary": "GET /artist-gate",
-        "description": "GET /artist-gate — this project's artist strictness and what it is holding. rank: any authenticated builder. The payload is ordinary board state — a policy value the instance already publishes as its own behaviour, and task ids/titles any builder can read on the hall — so a floor above requireBuilder would gate a fact the board already shows. Nothing here is writable. Response: mode 'off' | 'advisory' | 'strict' the project's setting as resolved since ISO string | null when it was last RAISED to strict holds boolean does anything hold a deploy now? truncated boolean `reviews` hit the scan cap — a floor reviews [{ id, created_at }] the open reviews that count halt { code, message, detail } | null the refusal, pre-composed `halt` is composed HERE rather than by the caller on purpose: ADR 0241 §4's second guard is that the refusal must name what holds the deploy and which control releases it, and a sentence assembled independently by each caller is a sentence that eventually says something different. One composer, one wording.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "description": "GET /artist-gate — this project's artist strictness and what it is holding. rank: any authenticated builder. The payload is ordinary board state — a policy value the instance already publishes as its own behaviour, and task ids/titles any builder can read on the hall — so a floor above requireBuilder would gate a fact the board already shows. Nothing here is writable. Response: mode 'off' | 'advisory' | 'strict' the project's setting as resolved since ISO string | null when it was last RAISED to strict holds boolean does anything hold a deploy now? truncated boolean `reviews` hit the scan cap — a floor reviews [{ id, created_at }] the open reviews that count halt { code, message, detail } | null the refusal, pre-composed `halt` is composed HERE rather than by the caller on purpose: ADR 0241 §4's second guard is that the refusal must name what holds the deploy and which control releases it, and a sentence assembled independently by each caller is a sentence that eventually says something different. One composer, one wording. A caller on this machine that reached the app DIRECTLY may also read it, without a session (task 1004205; owner decision 2026-09-23): that is how `bongos upgrade` on the box asks before moving the pin, and the box holds no builder session. Everything else still passes requireBuilder.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
         "x-rank": "any-builder",
         "x-source": "modules/lifecycle/routes/artist-gate.js",
         "responses": {

package/docs/module-api-changelog.md

@@ -2451,6 +2451,8 @@ is load-bearing: the script throws rather than guess if it is missing, and
   1.19.988 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.987 with no explicit bump. run 35909292753. (task 1002620)
   1.19.989 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
-        landed since 1.19.988 with no explicit bump. run 35911149318. (task 1002620)
+        landed since 1.19.988 with no explicit bump. run 35911817390. (task 1002620)
+  1.19.990 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.989 with no explicit bump. run 35912578496. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/core-release-pipeline.md

@@ -207,6 +207,11 @@ There are three ways past it, and the first two are the ordinary ones:
      the audit log as a self-override. It is the valve that stops a solo project deadlocking,
      not a routine step: the right answer to being gated is to fix the work or fix the grader.
 
+**`bongos upgrade` asks the same gate** (task 1004205): the vendored `upgrade.js --from` run
+refuses before the pin moves, with the same halt, the same three ways past it and the same two
+unknowns below — it reuses `go-live.js`'s reader. Until then only `go-live.js` asked, and an
+instance that moved its pin by hand moved it past open reviews.
+
 `go-live.js` prints the gate's level on every plan, held or not, so "why did nothing stop?" is
 answerable without going and looking. Two different unknowns, two different verdicts:
 

package/docs/recipes/upgrading-the-core.md

@@ -10,6 +10,7 @@
 
 0. **downgrade guard** (task [#1004009](https://example.com/builders#/task/1004009)) — a `--to` **older** than this instance's core is refused before anything moves, in one line naming both versions and the newest published release. "This instance's core" is the **newer** of what is installed and what is pinned, because a half-applied bump leaves the two apart and the pin is the thing about to be overwritten. `--force` does not waive it; `--allow-downgrade` does, and the run then says `DOWNGRADE` in its first line, its last line and its `core_upgrades` ledger note. Migrations are never reverted, so going backwards across one leaves the DB ahead of the code; and an instance subscribed to an update channel is taken forward again by the next sweep, so set it to `pinned` first if the downgrade is meant to hold. Auto-rollback (step 8) restores its own pin and is unaffected.
 1. **pre-flight** — module-compat vs the target core + a clean git tree (skip with `--force`).
+1a. **the artist gate** (task [#1004205](https://example.com/builders#/task/1004205), [ADR 0241](../adr/0241-the-artist-gate-is-a-per-project-deploy-gate-that-reads-a-state.md)) — asks the instance being upgraded, at the origin of `--health-url`, whether an unresolved artist review holds its deploy, and **refuses before anything moves** if one does. `--force` does not waive it, and a dry run reports it. Every change to a page files such a review (owner decision 2026-09-23), so on a `strict` project an upgrade waits until each has been looked at. The ways past it are ADR 0241's, unchanged: resolve or dismiss the review, lower `artist_gate` to `advisory`, or the project owner releases it (see [the release pipeline](core-release-pipeline.md)). It uses `go-live.js`'s own reader, so both paths decide one answer the same way: a gate that is there and errors halts; one that cannot be read (no `--health-url`, an older instance, the instance down) is printed as a note. A **downgrade** is never held — rolling back must not wait on a review. Before this, only `go-live.js` asked, so the vendored `--from` path this instance used moved its pin past open reviews. The instance answers this local request without a session (the box has none); a request through the proxy still needs one. So the **first** upgrade that carries this asks an instance still running the older route, gets a 401 and can only print the note — every upgrade after it holds.
 2. **bump the pin** — vendor the new `bongos-core-<version>.tgz` and rewrite the `"@bongos/core": "file:vendor/…"` dependency.
 3. **`npm install`** — `node_modules/@bongos/core` becomes the new version.
 3b. **verify the integrity pin** (task [#1002216](https://example.com/builders#/task/1002216)) — recompute `tree_sha256` over the installed core and check the vendored `.tgz` bytes against `tarball.sha256`, comparing to the trusted reference manifest (the committed `vendor/…manifest.json`; the installed inner manifest for `--registry`). Runs **before** migrate so a corrupted core never touches the DB. A **mismatch is fatal → rollback**; a missing reference warns (fatal with `--require-pin`); opt out with `--skip-pin-verify`.

package/modules/lifecycle/routes/artist-gate.js

@@ -50,7 +50,12 @@ module.exports = function buildArtistGateRouter() {
   // second guard is that the refusal must name what holds the deploy and which
   // control releases it, and a sentence assembled independently by each caller is
   // a sentence that eventually says something different. One composer, one wording.
-  router.get('/artist-gate', api.requireBuilder, async (req, res) => {
+  //
+  // A caller on this machine that reached the app DIRECTLY may also read it,
+  // without a session (task 1004205; owner decision 2026-09-23): that is how
+  // `bongos upgrade` on the box asks before moving the pin, and the box holds no
+  // builder session. Everything else still passes requireBuilder.
+  router.get('/artist-gate', unlessDirectLocalCall(api.requireBuilder), async (req, res) => {
     try {
       const gate = api.artistGate;
       const mode = gate.artistGateMode();
@@ -99,3 +104,21 @@ module.exports = function buildArtistGateRouter() {
 
   return router;
 };
+
+// A request from this machine with NO proxy hop. Public traffic always reaches
+// the app through the proxy (Caddy, behind Cloudflare), which sets a forwarding
+// header, so a loopback peer without one is a local process — the rule
+// src/bongos/metrics.js applies to its local scraper. The payload is ids, dates
+// and the policy level: nothing a process already on the box could not read.
+function isDirectLocalCall(req) {
+  const h = req.headers || {};
+  if (h['x-forwarded-for'] || h['x-real-ip'] || h.forwarded || h['cf-connecting-ip']) return false;
+  const peer = (req.socket && req.socket.remoteAddress) || '';
+  return peer === '127.0.0.1' || peer === '::1' || peer === '::ffff:127.0.0.1';
+}
+
+// Runs `requireSession` for everyone except a direct local call (above), which
+// goes straight to the handler with no builder attached.
+function unlessDirectLocalCall(requireSession) {
+  return (req, res, next) => (isDirectLocalCall(req) ? next() : requireSession(req, res, next));
+}

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.989",
+  "version": "1.19.990",
   "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/scripts/gds/upgrade-artist-gate.js

@@ -0,0 +1,46 @@
+'use strict';
+
+// scripts/gds/upgrade-artist-gate.js — the artist gate's deploy hold on the
+// UPGRADE path (task 1004205; ADR 0241).
+//
+// WHY. On a `strict` project an unresolved artist review holds the DEPLOY, never
+// the ship. Only go-live.js asked the gate, and cloudbongos.com moves its pin
+// with the vendored `upgrade.js --from` instead, so on this instance an open
+// review held nothing (2026-09-23: the gate answered holds:true and the upgrade
+// never read it). Every UI change now files such a review (owner decision
+// 2026-09-23, task 1004201), so this is where "the owner sees it before users
+// do" is actually enforced.
+//
+// It reuses go-live.js's reader and judgement verbatim, so both deploy paths
+// decide the same answer the same way: a hold or a broken gate halts, a gate
+// that cannot be read at all is a note. It asks the instance being upgraded,
+// at the origin of --health-url, because the box runs the instance it upgrades;
+// the instance answers a direct local request without a session (the route).
+// The FIRST upgrade carrying this asks an instance that still wants a session,
+// so it can only print the unread note — every upgrade after that holds.
+// Kept out of upgrade.js, which sits at the line cap.
+
+const { readArtistGate, artistGateEntries } = require('./go-live');
+
+const GATE_TIMEOUT_MS = 10_000;
+
+function unreadNote(why) {
+  return { halts: [], notes: [{ code: 'ARTIST_GATE_UNREAD', message: `could not read this instance's artist gate (${why}) — if the project runs artist_gate 'strict', an unresolved artist review may be holding this deploy and this upgrade cannot see it` }] };
+}
+
+// checkArtistGate — { halts, notes } for this instance's gate, go-live's shape.
+async function checkArtistGate({ healthUrl }, deps = {}) {
+  if (!healthUrl) return unreadNote('no --health-url to reach the instance by');
+  let origin;
+  try { origin = new URL(healthUrl).origin; } catch (_) { return unreadNote(`--health-url ${healthUrl} is not a URL`); }
+  const fetchImpl = deps.fetchImpl || fetch;
+  const call = async (method, urlPath) => {
+    const res = await fetchImpl(`${origin}${urlPath}`, { method, signal: AbortSignal.timeout(GATE_TIMEOUT_MS) });
+    let data = null;
+    try { data = await res.json(); } catch (_) { /* not JSON: readArtistGate reads it as "not a gate" */ }
+    return { status: res.status, ok: res.ok, data };
+  };
+  return artistGateEntries(await readArtistGate(call));
+}
+
+module.exports = { checkArtistGate };

package/scripts/gds/upgrade.js

@@ -5,7 +5,7 @@
 // Turns the former stub (which only ran a module-vs-core compatibility PRE-CHECK) into the real
 // channel a two-repo consumer uses to pull the Cloud Bongos core from version N to N+1:
 //
-//   pre-flight   clean git tree + module-compat vs the TARGET core version
+//   pre-flight   clean git tree + module-compat vs the TARGET core version + the artist gate (ADR 0241)
 //     → bump pin   vendor the new core .tgz, rewrite the package.json `file:` dependency
 //     → npm install  node_modules/@bongos/core becomes the new version
 //     → migrate      `npm run migrate` → the core's migrate.sh applies additive `core_*` migrations
@@ -13,13 +13,10 @@
 //     → restart      restart the instance's service so the new core is live
 //     → verify       installed package version == target (+ optional /healthz + ledger row)
 //
-// SCOPE (ADR 0100 §2, reshaped by ADR 0103 §4): the SMALLEST channel the FIRST real consumer needs
-// on its first core bump — driven by that consumer, not designed up front. That consumer is
-// emersonian-circles (task 1917): a greenfield npm-dependency instance that pins the core as
-//   "@bongos/core": "file:vendor/bongos-core-<ver>.tgz"
-// with `start`/`migrate` npm scripts and a materialized .claude/. Every step below maps to something
-// that consumer actually has. A published-registry source, rollback, and multi-consumer shapes are
-// deliberately OUT — they are follow-ups a second consumer's needs will define.
+// SCOPE (ADR 0100 §2, reshaped by ADR 0103 §4): first built for emersonian-circles (task 1917), an
+// npm-dependency instance pinning "@bongos/core": "file:vendor/bongos-core-<ver>.tgz" with
+// `start`/`migrate` npm scripts and a materialized .claude/; the registry source (ADR 0134) and
+// auto-rollback (task 2149) came later, with the consumers that needed them.
 //
 // Runs from the consumer instance root (default) or `--instance <dir>`. This script ships IN the core
 // package, so once a consumer is on core vN+1 its own `bongos upgrade` is this code. The FIRST bump
@@ -33,6 +30,7 @@ const crypto = require('node:crypto');
 const { spawnSync } = require('node:child_process');
 const { arg, hasFlag } = require('./cli-lib');
 const { parseSemver, compareSemver, isStable, listAvailableVersions } = require('./update-channel');
+const { checkArtistGate } = require('./upgrade-artist-gate');
 
 const CORE_PKG = '@bongos/core';
 const ARTIFACT = 'bongos-core';
@@ -1146,13 +1144,13 @@ async function runUpgrade(opts, deps = {}) {
     else log(`  ✓ pre-flight: database${db ? ` "${db}"` : ''} reachable as the current user`);
   }
 
-  // 1b. mandatory post-restart health check (audit H9 / task 1002222, finding F5). A bump that
-  //     brings the new core live via a managed restart (--service / --restart-cmd) MUST confirm it
-  //     actually serves — an upgrade that can't be health-checked can't be reported as a success.
-  //     Enforced here in PRE-FLIGHT, before anything is mutated, so there is nothing to roll back:
-  //     if this bump will restart the service and the check isn't explicitly opted out, a
-  //     --health-url is required. (No managed restart ⇒ nothing is brought live here ⇒ the check
-  //     does not apply; the operator restarts + verifies separately.)
+  // 1a. artist gate (ADR 0241, task 1004205): an open review holds the pin, --force too; a downgrade never waits.
+  const gate = isDowngrade ? { halts: [], notes: [] } : await (deps.checkArtistGate || checkArtistGate)(opts, deps);
+  for (const n of gate.notes) err(`  ! ${n.message}`);
+  if (gate.halts.length) return { ok: false, artistGate: true, error: gate.halts.map((h) => [h.message, h.detail].filter(Boolean).join('\n    ')).join('\n') };
+  // 1b. mandatory post-restart health check (audit H9 / task 1002222, F5): a bump that restarts the
+  //     service must prove it serves, so --health-url is required up front, before anything moves.
+  //     (No managed restart ⇒ nothing is brought live here ⇒ the operator restarts + verifies.)
   const willRestart = !!(opts.service || opts.restartCmd);
   if (!dryRun && opts.healthCheck !== false && willRestart && !opts.healthUrl) {
     return { ok: false, error: 'post-restart health check is mandatory for a bump that restarts the service, but no --health-url was given.\n  Pass --health-url <url> to confirm the new core serves after restart, or --no-health-check to explicitly skip the confirmation.' };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.989'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.990'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/artist_gate_route.mjs

@@ -37,7 +37,12 @@ db.listOpenArtistReviews = async (opts) => { queries.push(opts); return { review
 
 let mode = 'strict';
 let since = null;
-api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, rank: 'thetes' }; next(); };
+let signedIn = true;
+api.requireBuilder = (req, res, next) => {
+  if (!signedIn) return res.status(401).json({ error: { code: 'unauthenticated' } });
+  req.builder = { id: 7, rank: 'thetes' };
+  next();
+};
 // The route must resolve the level through the doorway's ONE reader; stubbing it
 // here is also what proves it does not read branding().project behind its back.
 api.artistGate = { ...gateModule, artistGateMode: () => mode, artistGateSince: () => since };
@@ -171,4 +176,68 @@ test('a database failure is a 500 with no internals, never a quiet "nothing hold
   db.listOpenArtistReviews = async (opts) => { queries.push(opts); return { reviews: rows, truncated: scanTruncated }; };
 });
 
+// ---- who may read it without a session (task 1004205) ---------------------------
+
+function getWith(path, headers) {
+  return new Promise((resolve, reject) => {
+    http.get(`${base}${path}`, { headers }, (res) => {
+      let d = '';
+      res.on('data', (c) => { d += c; });
+      res.on('end', () => { let j = null; try { j = JSON.parse(d); } catch { /* non-JSON */ } resolve({ status: res.statusCode, body: j }); });
+    }).on('error', reject);
+  });
+}
+
+test('the box asking its OWN instance directly reads the gate with no session — how `bongos upgrade` asks', async () => {
+  reset({ open: [review()] });
+  signedIn = false;
+  try {
+    const r = await getWith('/artist-gate', {});
+    assert.equal(r.status, 200);
+    assert.equal(r.body.holds, true);
+    assert.deepEqual(r.body.reviews, [{ id: '9001', created_at: '2026-09-12T00:00:00.000Z' }]);
+  } finally { signedIn = true; }
+});
+
+test('anything that came through a proxy still needs a session — public traffic never rides the local exception', async () => {
+  reset({ open: [review()] });
+  signedIn = false;
+  try {
+    for (const headers of [
+      { 'X-Forwarded-For': '203.0.113.9' },
+      { 'X-Real-IP': '203.0.113.9' },
+      { Forwarded: 'for=203.0.113.9' },
+      { 'CF-Connecting-IP': '203.0.113.9' },
+    ]) {
+      const r = await getWith('/artist-gate', headers);
+      assert.equal(r.status, 401, JSON.stringify(headers));
+    }
+  } finally { signedIn = true; }
+});
+
+test('a peer that is not this machine is not local, forwarding header or not — it needs a session', async () => {
+  reset({ open: [review()] });
+  signedIn = false;
+  try {
+    const out = await new Promise((resolve) => {
+      const r = { statusCode: 200 };
+      const res = {
+        status(c) { r.statusCode = c; return this; },
+        json(b) { r.body = b; resolve(r); return this; },
+        set() { return this; },
+        fail(code, o) { r.statusCode = (o && o.status) || 400; resolve(r); },
+      };
+      buildRouter().handle({ method: 'GET', url: '/artist-gate', headers: {}, socket: { remoteAddress: '203.0.113.9' } }, res, () => resolve({ statusCode: 404 }));
+    });
+    assert.equal(out.statusCode, 401);
+  } finally { signedIn = true; }
+});
+
+test('a signed-in builder behind the proxy reads it exactly as before', async () => {
+  reset({ open: [review()] });
+  const r = await getWith('/artist-gate', { 'X-Forwarded-For': '203.0.113.9' });
+  assert.equal(r.status, 200);
+  assert.equal(r.body.holds, true);
+});
+
 test.after(() => server.close());

package/tests/upgrade_artist_gate.mjs

@@ -0,0 +1,144 @@
+// tests/upgrade_artist_gate.mjs — the artist gate holds the pin on the UPGRADE
+// path too (task 1004205; ADR 0241).
+//
+// go-live.js consulted the gate; the vendored `upgrade.js --from` this instance
+// actually moves its pin with did not, so an open review held nothing. These
+// pin the gate reader against a fake instance, and runUpgrade refusing BEFORE
+// anything moves — with a downgrade (rolling back) never held.
+//
+// Run:  node tests/upgrade_artist_gate.mjs
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { makeRunner } from './helpers.mjs';
+import { checkArtistGate } from '../scripts/gds/upgrade-artist-gate.js';
+
+const require = createRequire(import.meta.url);
+const u = require('../scripts/gds/upgrade.js');
+const { test, summary } = makeRunner();
+
+// A fake instance: answers GET <origin>/api/bongos/artist-gate with `status` + `body`.
+function instance(status, body) {
+  const asked = [];
+  const fetchImpl = async (url, init) => {
+    asked.push({ url, method: init && init.method });
+    return { status, ok: status >= 200 && status < 300, json: async () => { if (body === undefined) throw new Error('not json'); return body; } };
+  };
+  return { asked, fetchImpl };
+}
+const HOLD = {
+  ok: true, mode: 'strict', holds: true, reviews: [{ id: '1004199' }],
+  halt: { code: 'ARTIST_REVIEW_UNRESOLVED', message: '1 unresolved artist review hold this deploy', detail: 'Held by task 1004199. Two ways out.' },
+};
+
+// ---- the reader ---------------------------------------------------------------
+
+await test('it asks the instance being upgraded, at the ORIGIN of --health-url', async () => {
+  const i = instance(200, { ok: true, mode: 'strict', holds: false, reviews: [], halt: null });
+  const r = await checkArtistGate({ healthUrl: 'http://127.0.0.1:3000/api/bongos/healthz' }, { fetchImpl: i.fetchImpl });
+  assert.deepEqual(i.asked, [{ url: 'http://127.0.0.1:3000/api/bongos/artist-gate', method: 'GET' }]);
+  assert.deepEqual(r, { halts: [], notes: [] }, 'strict with nothing open holds nothing');
+});
+
+await test('an open review on a strict project HALTS, naming the review and the way out', async () => {
+  const r = await checkArtistGate({ healthUrl: 'https://cloudbongos.com/api/bongos/healthz' }, { fetchImpl: instance(200, HOLD).fetchImpl });
+  assert.equal(r.halts.length, 1);
+  assert.equal(r.halts[0].code, 'ARTIST_REVIEW_UNRESOLVED');
+  assert.match(r.halts[0].detail, /1004199/);
+});
+
+await test('advisory and off hold nothing', async () => {
+  for (const mode of ['advisory', 'off']) {
+    const r = await checkArtistGate({ healthUrl: 'http://x/h' }, { fetchImpl: instance(200, { mode, holds: false, reviews: [], halt: null }).fetchImpl });
+    assert.deepEqual(r.halts, [], mode);
+  }
+});
+
+await test('a gate that is THERE and broken halts; one that cannot be read at all is a note', async () => {
+  assert.equal((await checkArtistGate({ healthUrl: 'http://x/h' }, { fetchImpl: instance(500, {}).fetchImpl })).halts[0].code, 'ARTIST_GATE_UNREADABLE');
+  for (const [status, body] of [[404, {}], [200, undefined], [200, { hello: 'an SPA page' }]]) {
+    const r = await checkArtistGate({ healthUrl: 'http://x/h' }, { fetchImpl: instance(status, body).fetchImpl });
+    assert.deepEqual(r.halts, [], `${status} → no halt`);
+    assert.equal(r.notes[0].code, 'ARTIST_GATE_UNREAD', `${status} → said out loud, never read as "nothing holds" silently`);
+  }
+  const down = await checkArtistGate({ healthUrl: 'http://x/h' }, { fetchImpl: async () => { throw new Error('ECONNREFUSED'); } });
+  assert.equal(down.notes[0].code, 'ARTIST_GATE_UNREAD');
+});
+
+await test('with no --health-url there is nothing to ask — a note, never a silent pass', async () => {
+  for (const healthUrl of [undefined, 'not a url']) {
+    const r = await checkArtistGate({ healthUrl }, { fetchImpl: async () => { throw new Error('must not be called'); } });
+    assert.deepEqual(r.halts, []);
+    assert.equal(r.notes[0].code, 'ARTIST_GATE_UNREAD');
+  }
+});
+
+// ---- runUpgrade -----------------------------------------------------------------
+
+function consumer(version = '1.14.1') {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-upgrade-gate-'));
+  writeFileSync(join(dir, 'package.json'), JSON.stringify({
+    name: 'c', version: '0.1.0', dependencies: { '@bongos/core': `file:vendor/bongos-core-${version}.tgz` }, scripts: { migrate: 'true', start: 'true' },
+  }, null, 2) + '\n');
+  mkdirSync(join(dir, 'node_modules', '@bongos', 'core'), { recursive: true });
+  writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'), JSON.stringify({ name: '@bongos/core', version }) + '\n');
+  return dir;
+}
+function tarball(version) {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, `bongos-core-${version}.tgz`), 'TGZ');
+  return join(src, `bongos-core-${version}.tgz`);
+}
+const run = (calls) => (cmd, args) => { calls.push(`${cmd} ${(args || []).join(' ')}`); return cmd === 'git' ? { status: 0, stdout: '' } : { status: 0 }; };
+const holding = async () => ({ halts: [{ code: 'ARTIST_REVIEW_UNRESOLVED', message: '1 unresolved artist review hold this deploy', detail: 'Held by task 1004199.' }], notes: [] });
+
+await test('runUpgrade REFUSES a held pin before anything moves — --force included', async () => {
+  for (const force of [false, true]) {
+    const dir = consumer();
+    const calls = [];
+    const res = await u.runUpgrade({ to: '1.15.0', from: tarball('1.15.0'), instance: dir, force, skipMigrate: true },
+      { log: () => {}, err: () => {}, run: run(calls), checkArtistGate: holding });
+    assert.equal(res.ok, false);
+    assert.equal(res.artistGate, true);
+    assert.match(res.error, /unresolved artist review/);
+    assert.match(res.error, /1004199/, 'names the review');
+    assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'the pin never moved');
+    assert.ok(!calls.some((c) => c.startsWith('npm')), 'nothing installed');
+  }
+});
+
+await test('a dry run reports the hold too — that is what a dry run is for', async () => {
+  const res = await u.runUpgrade({ to: '1.15.0', from: tarball('1.15.0'), instance: consumer(), dryRun: true, skipMigrate: true },
+    { log: () => {}, err: () => {}, run: run([]), checkArtistGate: holding });
+  assert.equal(res.ok, false);
+  assert.equal(res.artistGate, true);
+});
+
+await test('nothing open: the upgrade proceeds exactly as before, and a note is printed, not swallowed', async () => {
+  const errs = [];
+  const res = await u.runUpgrade({ to: '1.15.0', from: tarball('1.15.0'), instance: consumer(), dryRun: true, skipMigrate: true },
+    { log: () => {}, err: (m) => errs.push(m), run: run([]), checkArtistGate: async () => ({ halts: [], notes: [{ code: 'ARTIST_GATE_UNREAD', message: 'could not read this instance\'s artist gate (x)' }] }) });
+  assert.equal(res.ok, true);
+  assert.ok(errs.some((m) => /could not read this instance's artist gate/.test(m)));
+});
+
+await test('a DOWNGRADE is never held — rolling back must not wait on a review', async () => {
+  let asked = 0;
+  const res = await u.runUpgrade({ to: '1.14.0', from: tarball('1.14.0'), instance: consumer('1.14.1'), allowDowngrade: true, dryRun: true, skipMigrate: true },
+    { log: () => {}, err: () => {}, run: run([]), checkArtistGate: async () => { asked++; return holding(); } });
+  assert.equal(asked, 0);
+  assert.equal(res.ok, true);
+});
+
+await test('the gate runs from the pre-flight, before the pin step, and the reader is go-live\'s own', () => {
+  const whole = readFileSync(new URL('../scripts/gds/upgrade.js', import.meta.url), 'utf8');
+  const src = whole.slice(whole.indexOf('async function runUpgrade('));
+  const gateAt = src.indexOf('checkArtistGate)(opts, deps)');
+  assert.ok(gateAt > 0 && gateAt < src.indexOf('writePin(instanceDir'), 'checked before the pin is written');
+  const gateSrc = readFileSync(new URL('../scripts/gds/upgrade-artist-gate.js', import.meta.url), 'utf8');
+  assert.match(gateSrc, /require\('\.\/go-live'\)/, 'one reader and one judgement for both deploy paths');
+});
+
+summary();