@bongos/core 1.19.714 → 1.19.724

package/tests/cli_exit_no_abort.mjs

@@ -32,6 +32,7 @@ import assert from 'node:assert/strict';
 import { test } from 'node:test';
 import { spawnSync, spawn } from 'node:child_process';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
@@ -40,6 +41,10 @@ const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const API = path.join(ROOT, 'scripts', 'gds', 'api.js');
 const MAIN_AUDIT = path.join(ROOT, 'scripts', 'gds', 'main-audit.js');
 const CLI_LIB = path.join(ROOT, 'scripts', 'gds', 'cli-lib.js');
+// task 1002592 — the next two CLIs found ABORTING, converted under task 1002734's
+// standing rule (evidence, not a blanket sweep).
+const CLAIM = path.join(ROOT, 'scripts', 'gds', 'claim.js');
+const LAND_WATCH = path.join(ROOT, 'scripts', 'gds', 'land-watch.js');
 const DEAD_BASE = 'http://127.0.0.1:9'; // discard port — connection refused, instantly
 
 // Point a CLI at a base URL. DERIVED, not hardcoded: instance-config resolves
@@ -47,8 +52,14 @@ const DEAD_BASE = 'http://127.0.0.1:9'; // discard port — connection refused,
 // literal here would (a) add to the legacy-GDS ratchet the rename is retiring and
 // (b) silently stop steering the CLI on any instance whose brand pack sets a
 // different prefix — the test would then hit the REAL API instead of the stub.
-const { envPrefix } = createRequire(import.meta.url)(path.join(ROOT, 'src', 'instance-config.js'));
+const ic = createRequire(import.meta.url)(path.join(ROOT, 'src', 'instance-config.js'));
+const { envPrefix } = ic;
 const API_BASE_ENV = `${envPrefix()}_API_BASE`;
+// Derived for the same reason the base env is: a literal would stop steering the
+// CLI on any instance whose brand pack renames the config dir, and the test would
+// then read the operator's REAL session instead of the throwaway one.
+const CONFIG_DIR_NAME = ic.configDirName();
+const SESSION_FILENAME = ic.SESSION_FILENAMES[0];
 const atBase = (url) => ({ [API_BASE_ENV]: url });
 
 // The native abort prints this and nothing else can be relied on; it is NOT a
@@ -104,8 +115,79 @@ const s = http.createServer((q, r) => {
 s.listen(0, '127.0.0.1', () => console.log('PORT=' + s.address().port));
 `;
 
-function startStub() {
-  const proc = spawn(process.execPath, ['-e', STUB_SRC], { stdio: ['ignore', 'pipe', 'ignore'] });
+// task 1002592 — claim.js needs a stub that ROUTES: the claim POST decides which
+// path is under test, while every other call it makes (learnings, recall, /me, the
+// task fetch land-watch does) is best-effort and only has to answer something
+// parseable. `status` picks the path: 409 serves the real REBASE_REQUIRED envelope
+// so the refusal rendering is proved end-to-end, 201 serves a claim so the heavier
+// success teardown runs.
+const claimStubSrc = (status) => `
+const http = require('node:http');
+const REFUSAL = ${JSON.stringify({
+  error: {
+    code: 'REBASE_REQUIRED',
+    message: 'REBASE_REQUIRED',
+    details: {
+      hint: 'Your queue is gated: 1 confirmed task(s) await your rebase (task 1003575). Clear it with /strand-fix N (works on any machine).',
+      rebaseTasks: [{ id: 1003575, title: 'Stub owed task', reason: 'strand:unresolvable_conflict:stub.md' }],
+    },
+  },
+})};
+const CLAIMED = ${JSON.stringify({
+  claim: { id: 9001 },
+  task: {
+    id: 4242, title: 'Stub task', version_id: 'BONGOS-V2', touches: [],
+    credits_reward: 0, priority: 1, description: '', parallel_safe: false,
+  },
+  reward: { mode: 'cost-plus-only', perTaskCredit: false },
+})};
+const s = http.createServer((q, r) => {
+  let body = '';
+  q.on('data', (c) => { body += c; });
+  q.on('end', () => {
+    const isClaim = q.method === 'POST' && /\\/claims$/.test(q.url.split('?')[0]);
+    const code = isClaim ? ${status} : 200;
+    const payload = isClaim ? (${status} === 201 ? CLAIMED : REFUSAL) : {};
+    r.writeHead(code, { 'Content-Type': 'application/json' });
+    r.end(JSON.stringify(payload));
+  });
+});
+s.listen(0, '127.0.0.1', () => console.log('PORT=' + s.address().port));
+`;
+
+// task 1002592 — claim.js and land-watch.js read a SESSION and (for land-watch) a
+// breadcrumb directory, both under the config home, which instance-config derives
+// from os.homedir(). Node resolves that from HOME / USERPROFILE, so overriding both
+// gives each test a throwaway config tree: the developer's real session is never
+// read, their real breadcrumb dir is never written, and a test can plant exactly
+// the state it needs. Without this, planting a breadcrumb would mean writing into
+// the operator's own ~/.config and racing whatever land-watch is genuinely tracking.
+function makeHome({ apiBase = DEAD_BASE, breadcrumbTaskId = null } = {}) {
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'cli-exit-home-'));
+  const cfg = path.join(home, '.config', CONFIG_DIR_NAME);
+  fs.mkdirSync(cfg, { recursive: true });
+  fs.writeFileSync(
+    path.join(cfg, SESSION_FILENAME),
+    JSON.stringify({ token: 'stub-token-not-a-real-credential', api_base: apiBase }),
+    'utf8'
+  );
+  if (breadcrumbTaskId) {
+    const pending = path.join(cfg, 'pending-land');
+    fs.mkdirSync(pending, { recursive: true });
+    fs.writeFileSync(
+      path.join(pending, `${breadcrumbTaskId}.json`),
+      JSON.stringify({ taskId: String(breadcrumbTaskId), at: new Date().toISOString() }),
+      'utf8'
+    );
+  }
+  return home;
+}
+
+const isolatedHome = (home) => ({ HOME: home, USERPROFILE: home });
+
+function startStub(opts = {}) {
+  const src = opts.claimStatus ? claimStubSrc(opts.claimStatus) : STUB_SRC;
+  const proc = spawn(process.execPath, ['-e', src], { stdio: ['ignore', 'pipe', 'ignore'] });
   return new Promise((resolve, reject) => {
     let buf = '';
     const timer = setTimeout(() => { proc.kill(); reject(new Error('stub server did not report a port')); }, 10_000);
@@ -152,6 +234,177 @@ test('api.js routes its post-request exits through cliExit, not process.exit', (
   assert.match(afterRequest, /cliExit\(/, 'the post-request paths must set the exit code via cliExit');
 });
 
+// ---- claim.js + land-watch.js (task 1002592) -------------------------------
+//
+// WHAT EACH KIND OF TEST BELOW ACTUALLY GUARDS — measured, not assumed, because
+// claiming otherwise is how a suite comes to look like coverage it does not have.
+// With the hard exits deliberately restored in both scripts, the STATIC checks
+// went red and every behavioural test below stayed GREEN, including the ones that
+// make a real HTTP round trip to the local stub. That reproduces, for these two
+// CLIs, what task 1003772 found for main-audit.js: a localhost stub tears down too
+// little machinery to trip the abort. The aborts these tests exist for were all
+// measured against the REAL API over TLS.
+//
+// So: the static checks are the net for the ABORT. The behavioural tests are still
+// worth their runtime — they pin the exit CODES callers branch on (claim 0 vs 1,
+// land-watch 0 on every path), they prove the scripts TERMINATE rather than hang,
+// which is the documented conversion trap, and the refusal case proves the
+// REBASE_REQUIRED rendering reaches a terminal end-to-end.
+// Both were MEASURED aborting 3/3 on Windows 11 / Node v24.19.0 before the
+// conversion, and 5/5 clean after — claim.js on its refusal path (exit 127 where
+// it computed 1) and land-watch.js on its network path (exit 127 where it always
+// intends 0). Task 1002734 deliberately left the wider CLI surface alone and set
+// the bar at "found ABORTING, not merely fetching-then-exiting"; these two cleared
+// it. Neither file arms a timer, so the documented conversion trap — a hard exit
+// masking a leak, turning the crash into a HANG — does not apply here; the
+// behavioural runs below still assert termination rather than assuming it.
+
+test('claim.js routes its post-request exits through cliExit, not process.exit', () => {
+  const src = fs.readFileSync(CLAIM, 'utf8');
+  // The pre-request guards stay as hard exits, exactly as api.js kept its two:
+  // the worktree guard and the usage banner both run before any network work.
+  // Everything from the claim POST onward must drain instead.
+  // Anchor on the CLAIM request itself, not on `cliClient()` — the client is also
+  // built inside best-effort helpers defined near the top of the file, so that
+  // string would slice from the wrong place and quietly measure nothing.
+  const marker = 'let r = await postClaim();';
+  const i = src.indexOf(marker);
+  assert.ok(i !== -1, 'could not find the claim request site in claim.js — this guard is reading the wrong shape');
+  assert.equal(src.split(marker).length - 1, 1, 'the anchor must be unique or the slice is arbitrary');
+  const afterRequest = src.slice(i).replace(/\/\/[^\n]*/g, '');
+  assert.ok(
+    !/process\.exit\s*\(/.test(afterRequest),
+    'no process.exit() may remain after the claim request is issued — that is what aborts node on Windows '
+    + 'and turns a refusal\'s exit 1 into 127'
+  );
+  assert.match(afterRequest, /cliExit\(/, 'the post-request paths must set the exit code via cliExit');
+});
+
+test('claim.js keeps its PRE-request guards as hard exits', () => {
+  const src = fs.readFileSync(CLAIM, 'utf8');
+  const beforeRequest = src.slice(0, src.indexOf('let r = await postClaim();'));
+  assert.match(
+    beforeRequest, /process\.exit\s*\(/,
+    'the usage + worktree guards run before any network work; converting them buys nothing '
+    + 'and a cliExit there would let execution continue past a refusal'
+  );
+});
+
+test('land-watch.js routes every exit through cliExit, not process.exit', () => {
+  const src = fs.readFileSync(LAND_WATCH, 'utf8');
+  const stripped = src.replace(/\/\/[^\n]*/g, '');
+  assert.ok(
+    !/process\.exit\s*\(/.test(stripped),
+    'no process.exit() may remain in land-watch.js — it is HOOK-INVOKED and exits 0 on every path '
+    + 'on purpose, so the abort made the one script written never to fail always report 127'
+  );
+  assert.match(src, /cliExit\(/, 'the exit paths must set the exit code via cliExit');
+});
+
+test('land-watch.js exits 0 and TERMINATES with no pending lands (fast path, no network)', () => {
+  const r = spawnSync(process.execPath, [LAND_WATCH], {
+    cwd: ROOT,
+    encoding: 'utf8',
+    timeout: 60_000, // dropping a hard exit trades a crash for a HANG if a handle leaks
+    env: { ...process.env, ...atBase(DEAD_BASE), ...isolatedHome(makeHome()) },
+  });
+  assert.notEqual(r.signal, 'SIGTERM', 'timed out — draining left a handle armed');
+  assert.doesNotMatch(r.stderr || '', ABORT_RE, `native abort on the land-watch path:\n${r.stderr}`);
+  assert.equal(r.status, 0, `land-watch must exit 0 on every path, got ${r.status} (127 = the abort)`);
+});
+
+// THE PATH THAT ACTUALLY ABORTED. The fast path above returns before any network
+// work, so on its own it proves nothing about this bug: the measured 3/3 aborts
+// were on the NETWORK path (breadcrumb present → watch() → fetchTask() → a real
+// round trip → exit). Plant a breadcrumb in an isolated HOME and serve a real 200
+// so the full teardown runs, exactly as api.js's stub-server test does.
+test('land-watch.js exits 0 after a REAL request — the teardown that aborted 3/3', async () => {
+  const { proc, port } = await startStub();
+  try {
+    for (let i = 0; i < 3; i++) {
+      // classifyLand drops a non-shipped breadcrumb after one pass, so re-plant it.
+      const home = makeHome({ apiBase: `http://127.0.0.1:${port}`, breadcrumbTaskId: '4242' });
+      const r = spawnSync(process.execPath, [LAND_WATCH], {
+        cwd: ROOT,
+        encoding: 'utf8',
+        timeout: 60_000,
+        env: { ...process.env, ...atBase(`http://127.0.0.1:${port}`), ...isolatedHome(home) },
+      });
+      assert.notEqual(r.signal, 'SIGTERM', `run ${i + 1} timed out — draining left a handle armed`);
+      assert.doesNotMatch(r.stderr || '', ABORT_RE, `run ${i + 1} aborted natively on the network path:\n${r.stderr}`);
+      assert.equal(r.status, 0, `run ${i + 1} exited ${r.status} (127 = the abort); stderr: ${r.stderr}`);
+      // Prove the run really took the network path rather than the idle fast-path,
+      // or this test would silently degrade into the one above.
+      assert.doesNotMatch(r.stderr || '', /no pending lands/,
+        `run ${i + 1} took the idle fast path — the breadcrumb was not seen, so the network teardown was never exercised`);
+    }
+  } finally {
+    proc.kill();
+  }
+});
+
+// claim.js. Its exits are post-request and it was measured aborting 3/3 on the
+// refusal path. Both paths below run against the stub in an isolated HOME with a
+// throwaway session, so no real API is touched and the developer's own config is
+// never read or written. `--here` because CI may check out the MAIN checkout,
+// where the worktree guard would refuse at exit 2 before any request is made.
+test('claim.js exits 1 without aborting on a REFUSED claim — measured 3/3 aborting before', async () => {
+  const { proc, port } = await startStub({ claimStatus: 409 });
+  try {
+    const home = makeHome({ apiBase: `http://127.0.0.1:${port}` });
+    for (let i = 0; i < 3; i++) {
+      const r = spawnSync(process.execPath, [CLAIM, '4242', '--here'], {
+        cwd: ROOT,
+        encoding: 'utf8',
+        timeout: 60_000,
+        env: { ...process.env, ...atBase(`http://127.0.0.1:${port}`), ...isolatedHome(home) },
+      });
+      assert.notEqual(r.signal, 'SIGTERM', `run ${i + 1} timed out — draining left a handle armed`);
+      assert.doesNotMatch(r.stderr || '', ABORT_RE, `run ${i + 1} aborted natively:\n${r.stderr}`);
+      assert.equal(r.status, 1, `a refused claim must exit 1, got ${r.status} (127 = the abort); stderr: ${r.stderr}`);
+      // End-to-end proof that the new REBASE_REQUIRED rendering reaches a terminal,
+      // not just the unit test: the stub refuses with that exact envelope.
+      //
+      // Assert on wording only the BRANCH produces. Matching the hint text alone
+      // would pass with the branch disabled, because the generic fallback also
+      // prints d.hint now — measured, not assumed: a probe that disabled the branch
+      // kept this test green until these two assertions replaced it.
+      assert.match(r.stderr, /queue is gated/i, 'the REBASE_REQUIRED branch must render, not the bare fallback');
+      assert.match(r.stderr, /flagged: strand:unresolvable_conflict/, 'the branch must surface why the task was flagged');
+      assert.match(r.stderr, /strand-fix/, 'the server hint must reach the builder, not be dropped on the floor');
+      assert.match(r.stderr, /task 1003575/, 'the owed task must be named');
+    }
+  } finally {
+    proc.kill();
+  }
+});
+
+// THE OPEN QUESTION THE TASK FLAGGED, now answered rather than assumed: a
+// SUCCESSFUL claim leaves main() by `return` with no explicit exit, so it was never
+// covered by the refusal measurement above. It is also the heavier teardown — the
+// success path makes several further best-effort calls after the claim — which is
+// exactly the shape that aborted for api.js. Measured here: clean, exit 0.
+test('claim.js exits 0 without aborting on a SUCCESSFUL claim — the heavier teardown', async () => {
+  const { proc, port } = await startStub({ claimStatus: 201 });
+  try {
+    const home = makeHome({ apiBase: `http://127.0.0.1:${port}` });
+    for (let i = 0; i < 3; i++) {
+      const r = spawnSync(process.execPath, [CLAIM, '4242', '--here'], {
+        cwd: ROOT,
+        encoding: 'utf8',
+        timeout: 60_000,
+        env: { ...process.env, ...atBase(`http://127.0.0.1:${port}`), ...isolatedHome(home) },
+      });
+      assert.notEqual(r.signal, 'SIGTERM', `run ${i + 1} timed out — draining left a handle armed`);
+      assert.doesNotMatch(r.stderr || '', ABORT_RE, `run ${i + 1} aborted natively on the success path:\n${r.stderr}`);
+      assert.equal(r.status, 0, `a successful claim must exit 0, got ${r.status} (127 = the abort); stderr: ${r.stderr}`);
+      assert.match(r.stdout, /Claimed task/, 'the success output must still be produced');
+    }
+  } finally {
+    proc.kill();
+  }
+});
+
 // ---- main-audit.js — the deploy gate (task 1003772) ------------------------
 // Ranges are always HEAD..HEAD: it resolves on every checkout including a shallow
 // CI clone, audits zero commits, and still runs the WHOLE pipeline — fetchRankMap

package/tests/credit_log_single_writer.mjs

@@ -0,0 +1,94 @@
+// tests/credit_log_single_writer.mjs
+//
+// Task 1003641 — the balance is moved by the TRIGGER, and by nothing else.
+//
+// THE BUG. scripts/gds/backfill-task-rewards.js applyPlan() did both: INSERT INTO
+// credit_log (which fires trg_credit_log_apply AFTER INSERT) *and* a separate
+// `UPDATE builders SET total_credits = total_credits + $1`. The trigger had already
+// applied that delta, so every credit the script minted landed twice. A real
+// financial-ledger bug, and the kind that is invisible in review because each half
+// looks correct on its own.
+//
+// WHY THIS FILE IS NOT JUST A TEST OF THAT ONE LINE. The invariant is repo-wide:
+// exactly one place applies a credit_log delta to builders.total_credits. Every
+// other writer already relied on the trigger; only the backfill script double-wrote.
+// So the durable guard is "no credit_log writer also updates the balance", which
+// catches the NEXT script someone writes as well as this one.
+//
+// The existing tests/backfill_task_rewards.mjs never referenced applyPlan,
+// total_credits or the trigger at all, which is how this survived. Source
+// assertions, because the DB-free gate cannot run SQL; runtime behaviour is proven
+// against real Postgres at deploy.
+//
+// Run:  node tests/credit_log_single_writer.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (...p) => fs.readFileSync(path.join(ROOT, ...p), 'utf8');
+// Comments carry the rationale; strip them before asserting on the executable body
+// so a comment ABOUT the bug can never satisfy an assertion against it.
+const code = (src) => src
+  .replace(/^\s*\/\/.*$/gm, '')
+  .replace(/\/\*[\s\S]*?\*\//g, '');
+
+// Every file in the repo that inserts a credit_log row.
+const WRITERS = [
+  ['scripts', 'gds', 'backfill-task-rewards.js'],
+  ['scripts', 'gds', 'backfill-subagent-rewards.js'],
+  ['modules', 'economy', 'achievements.js'],
+  ['modules', 'economy', 'credits.js'],
+  ['modules', 'lifecycle', 'db-rank-authz.js'],
+  ['src', 'bongos', 'db.js'],
+];
+
+test('the trigger is the ONE place a credit_log delta reaches total_credits', () => {
+  const mig = read('migrations', '003_pms.sql');
+  assert.match(mig, /CREATE OR REPLACE FUNCTION pms_apply_credit\(\)/);
+  assert.match(mig, /SET total_credits = total_credits \+ NEW\.delta/,
+    'the trigger applies the delta');
+  assert.match(mig, /AFTER INSERT ON credit_log/,
+    'on insert, so any INSERT has already moved the balance');
+});
+
+test('no credit_log writer ALSO updates builders.total_credits', () => {
+  // The invariant. A writer that does both double-credits, silently.
+  const offenders = [];
+  for (const parts of WRITERS) {
+    const src = code(read(...parts));
+    if (!/INSERT INTO credit_log/i.test(src)) continue; // moved on; not our business
+    // Match an ASSIGNMENT, not a mention. `UPDATE builders SET rank = $2 ...
+    // RETURNING id, ..., total_credits, ...` READS the column and must not trip
+    // this — two files do exactly that, and an earlier draft of this test flagged
+    // both as double-writers. The two shapes that actually move a balance are the
+    // self-referential increment and a direct set.
+    const writesBalance = /\btotal_credits\s*=\s*total_credits/i.test(src)
+      || /SET\s+total_credits\s*=/i.test(src);
+    if (writesBalance) offenders.push(parts.join('/'));
+  }
+  assert.deepEqual(offenders, [],
+    `these insert a credit_log row AND move the balance themselves, so every credit lands twice: ${offenders.join(', ')}`);
+});
+
+test('backfill-task-rewards.js specifically — the regression that cost real credits', () => {
+  const src = read('scripts', 'gds', 'backfill-task-rewards.js');
+  assert.match(src, /INSERT INTO credit_log/, 'it still mints the audit row');
+  assert.doesNotMatch(code(src), /\btotal_credits\s*=/i,
+    'and must never assign total_credits — the trigger owns the balance');
+  // The reason WHY must survive too, or the next reader re-adds it.
+  assert.match(src, /trg_credit_log_apply applies the delta/,
+    'the call site explains why there is no balance update here');
+});
+
+test('the idempotency key still guards re-runs', () => {
+  // Removing the double-write must not disturb the other half of this script's
+  // safety: a second run of the same backfill must mint nothing.
+  const src = code(read('scripts', 'gds', 'backfill-task-rewards.js'));
+  assert.match(src, /SELECT 1 FROM credit_log WHERE task_id = \$1 AND reason = \$2/,
+    'the per-task idempotency re-check inside the transaction');
+  assert.match(src, /BACKFILL_REASON/, 'keyed on the backfill reason');
+});

package/tests/currency_label.mjs

@@ -51,11 +51,14 @@ test('clientBranding exposes project policy — the settings read-back (task 100
   // `visibility` — the join door — joined the block in task 1002324 (ADR 0182 D1);
   // `joinGrant` — what a PUBLIC join grants — in task 1002331 (ADR 0247), defaulting
   // to `full`, the value that narrows nothing, so an un-pushed instance is unchanged
+  // `artistGate` joined in task 1003575 (ADR 0241) and is the ONE key here whose
+  // fallback is not today's behaviour: 'strict' is the owner's ruling, safe as a
+  // default because it can only ever delay a pin move, never a builder's ship.
   assert.deepEqual(clientBranding({}).project,
-    { platformVisibility: 'public', joinability: 'apply', visibility: 'public', joinGrant: 'full' });
+    { platformVisibility: 'public', joinability: 'apply', visibility: 'public', joinGrant: 'full', artistGate: 'strict' });
   assert.deepEqual(
-    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view' } }).project,
-    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view' },
+    clientBranding({ project: { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view', artistGate: 'off' } }).project,
+    { platformVisibility: 'gated', joinability: 'invite_only', visibility: 'stealth', joinGrant: 'view', artistGate: 'off' },
     'what the instance actually resolved (env override included) is what it publishes');
 });
 
@@ -74,7 +77,11 @@ test('clientBranding is a SMALL allow-list — no server-only field leaks to the
   // `project` joined the allow-list in task 1003140: the per-project policy is public
   // by nature and is the settings read-back a manage page needs (see clientBranding).
   assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'project', 'rankLabels', 'reward', 'theme']);
-  assert.deepEqual(Object.keys(projected.project).sort(), ['joinGrant', 'joinability', 'platformVisibility', 'visibility']);
+  // `artistGate` joined in task 1003575 (ADR 0241) — the project's artist strictness,
+  // public for the same read-back reason as its neighbours. Its companion stamp
+  // (artistGateSince) deliberately does NOT: that is platform bookkeeping the server
+  // reads, and no browser surface has a question it answers.
+  assert.deepEqual(Object.keys(projected.project).sort(), ['artistGate', 'joinGrant', 'joinability', 'platformVisibility', 'visibility']);
   for (const leak of ['domains', 'repo', 'db', 'envPrefix', 'llmProjectName']) {
     assert.equal(projected[leak], undefined, `${leak} must not reach the client`);
   }

package/tests/go_live.mjs

@@ -25,6 +25,7 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
 import { createRequire } from 'node:module';
+import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -109,6 +110,149 @@ test('an undetermined divergence halts and does not fall through to a bump', ()
   assert.equal(p.from, null, 'must not invent a from-version');
 });
 
+// ---------------------------------------------------------------------------
+// The artist gate (ADR 0241, task 1003575)
+//
+// This is the one halt that comes from a PERSON'S queue rather than from git, so
+// what these pin is the boundary around it: it stops a PIN MOVE, it names its own
+// remedy, and it never fires on anything but a definite 'strict'-with-open-reviews
+// answer. A gate that halted on "I could not tell" would brick deploys on an
+// unrelated outage with no task id to release against — the blocked-state-that-
+// does-not-explain-itself failure ADR 0241 §4 was written against.
+// ---------------------------------------------------------------------------
+
+// The shape readArtistGate() resolves to, as the live instance reports it.
+const gate = (over = {}) => ({ mode: 'strict', since: null, holds: false, reviews: [], halt: null, ...over });
+const heldGate = (n = 1) => gate({
+  holds: true,
+  reviews: Array.from({ length: n }, (_, i) => ({ id: String(9000 + i), title: 'Artist review: …' })),
+  halt: {
+    code: 'ARTIST_REVIEW_UNRESOLVED',
+    message: `${n} unresolved artist review${n === 1 ? '' : 's'} hold this deploy — the project runs artist_gate 'strict'`,
+    detail: 'Held by task 9000. Two ways out … POST /tasks/:id/override-request …',
+  },
+});
+
+test('an unresolved artist review HALTS the pin move', () => {
+  const p = G.planGoLive({ div: div(), target: okTarget, targetVersion: '1.19.306', artistGate: heldGate(2) });
+  const h = p.halts.find((x) => x.code === 'ARTIST_REVIEW_UNRESOLVED');
+  assert.ok(h, 'expected ARTIST_REVIEW_UNRESOLVED');
+  // The refusal has to carry its own way out, or it is the stall ADR 0162 retired.
+  assert.match(h.detail, /override-request/);
+});
+
+test('a gate that holds nothing halts nothing — at any level', () => {
+  for (const mode of ['off', 'advisory', 'strict']) {
+    const p = G.planGoLive({ div: div(), target: okTarget, targetVersion: '1.19.306', artistGate: gate({ mode }) });
+    assert.equal(p.halts.length, 0, `${mode}: ${JSON.stringify(p.halts)}`);
+  }
+});
+
+test('an UNREAD gate is a note, never a halt — and never renders as "nothing holds"', () => {
+  // No session, or an instance too old to serve the route: we do not know the
+  // gate applies at all, and halting every deploy on that would brick the pin
+  // with no task id to release against.
+  const p = G.planGoLive({
+    div: div(), target: okTarget, targetVersion: '1.19.306',
+    artistGate: { unread: 'this instance does not serve /artist-gate — it predates ADR 0241' },
+  });
+  assert.equal(p.halts.length, 0, 'not knowing must not brick the pin');
+  const n = p.notes.find((x) => x.code === 'ARTIST_GATE_UNREAD');
+  assert.ok(n, 'but it must be REPORTED — "could not tell" is not "nothing holds"');
+  assert.match(n.message, /may be holding/, 'the wording must not claim the gate is clear');
+});
+
+test('a gate that is THERE and BROKEN halts — the fail-closed half', () => {
+  // The other side of the line: the route exists and 500s. We know the gate
+  // applies and cannot get an answer from it, so deploying past would be a
+  // quieter way through than the owner's own override — the asymmetry to refuse.
+  const p = G.planGoLive({
+    div: div(), target: okTarget, targetVersion: '1.19.306',
+    artistGate: { broken: 'GET /artist-gate returned 500' },
+  });
+  const h = p.halts.find((x) => x.code === 'ARTIST_GATE_UNREADABLE');
+  assert.ok(h, 'expected ARTIST_GATE_UNREADABLE');
+  assert.match(h.detail, /fault on the instance/, 'and it must point at the instance, not at an artist');
+  assert.equal(p.notes.find((x) => x.code === 'ARTIST_GATE_UNREAD'), undefined, 'one verdict, not two');
+});
+
+test('artistGateEntries is the shared composer, so the gitless lane cannot skip the gate', () => {
+  // The on-box lane builds its plan without planGoLive; it reaches the same halt
+  // through this, which is what stops "no git checkout" from meaning "no gate".
+  assert.equal(G.artistGateEntries(heldGate()).halts[0].code, 'ARTIST_REVIEW_UNRESOLVED');
+  assert.deepEqual(G.artistGateEntries(null), { halts: [], notes: [] });
+  assert.equal(G.artistGateEntries({ unread: 'no session' }).notes[0].code, 'ARTIST_GATE_UNREAD');
+});
+
+// ---------------------------------------------------------------------------
+// readArtistGate — the network leg.
+//
+// This is tested rather than left to the file's ssh/spawnSync boundary because a
+// mistake here is INVISIBLE: cli-lib's apiCall composes `${origin}${path}`, so a
+// path missing its `/api/bongos` prefix lands on the origin's catch-all and the
+// gate reports itself unread on every instance — including the ones that fully
+// support it — while the plan reads exactly like a clean run. It shipped that way
+// once. The URL is pinned against the route's REAL mount point in the generated
+// OpenAPI spec, so a rename on either side reds this rather than going quiet.
+// ---------------------------------------------------------------------------
+
+test('the path it requests is the one the server actually mounts', () => {
+  // The spec's paths are relative to its server base, and apiCall prepends
+  // nothing — so the URL go-live builds must be base + path, assembled from the
+  // spec rather than retyped. A rename on either side reds this.
+  const spec = JSON.parse(fs.readFileSync(new URL('../docs/api/openapi.json', import.meta.url), 'utf8'));
+  const bases = (spec.servers || []).map((s) => s.url);
+  const full = new Set(bases.flatMap((b) => Object.keys(spec.paths || {}).map((p) => `${b}${p}`)));
+  assert.ok(full.has(G.ARTIST_GATE_PATH),
+    `go-live requests ${G.ARTIST_GATE_PATH}, which the API spec does not serve — it would hit the origin's catch-all and read as "unread" forever`);
+  assert.match(G.ARTIST_GATE_PATH, /^\/api\//, 'apiCall does not prepend an API prefix — the path must carry it');
+});
+
+test('a real answer is parsed; a 200 that is NOT this route reads as unread, never as "nothing holds"', async () => {
+  const seen = [];
+  const call = async (method, path, body, opts) => { seen.push({ method, path, opts }); return call._res; };
+
+  call._res = { status: 200, ok: true, data: { mode: 'strict', since: null, holds: true, reviews: [{ id: '9001' }], halt: { message: 'm', detail: 'd' } } };
+  const got = await G.readArtistGate(call);
+  assert.deepEqual(seen[0].method, 'GET');
+  assert.equal(seen[0].path, G.ARTIST_GATE_PATH);
+  assert.equal(got.mode, 'strict');
+  assert.ok(got.halt, 'a real halt survives the read');
+
+  // An SPA index.html from a catch-all, or a proxy's own page: 200, no gate. The
+  // one failure that would wave a deploy through in silence.
+  call._res = { status: 200, ok: true, data: { raw: '<!doctype html><html>…' } };
+  const spa = await G.readArtistGate(call);
+  assert.ok(spa.unread, 'a 200 from something else is NOT a gate that holds nothing');
+  assert.equal(spa.halt, undefined);
+});
+
+test('every failure shape resolves — 404 and a lost connection are notes, a 5xx is the halt', async () => {
+  const res = (r) => async () => r;
+  assert.match((await G.readArtistGate(res({ status: 404, ok: false, data: {} }))).unread, /predates ADR 0241/);
+  assert.match((await G.readArtistGate(res({ status: 401, ok: false, data: {} }))).unread, /401/);
+  assert.match((await G.readArtistGate(res({ status: 500, ok: false, data: {} }))).broken, /500/);
+  assert.match((await G.readArtistGate(res({ status: 503, ok: false, data: {} }))).broken, /503/);
+  // It must never throw: a go-live that crashes on a gate read is worse than one
+  // that halts on it.
+  const thrower = async () => { throw new Error('ECONNREFUSED'); };
+  assert.match((await G.readArtistGate(thrower)).unread, /ECONNREFUSED/);
+});
+
+test('the level vocabulary go-live checks against is the gate\'s own', async () => {
+  const gate = await import('../src/bongos/artist-gate.js');
+  assert.deepEqual([...G.ARTIST_GATE_LEVELS].sort(), [...gate.ARTIST_GATE_LEVELS].sort(),
+    'the mirrored list must not drift from src/bongos/artist-gate.js');
+});
+
+test('the plan SHOWS the gate level even when nothing is held', () => {
+  const out = G.renderPlan(
+    { ...G.planGoLive({ div: div(), target: okTarget, targetVersion: '1.19.306', artistGate: gate({ mode: 'advisory' }) }), artistGate: gate({ mode: 'advisory' }) },
+    { targetName: 'web' }
+  );
+  assert.match(out, /artist gate\s+advisory/, '"why did nothing stop?" must be answerable from the plan');
+});
+
 // ---------------------------------------------------------------------------
 // Shell safety — this builds a command that runs as root over ssh
 // ---------------------------------------------------------------------------

package/tests/helpers.mjs

@@ -330,6 +330,14 @@ export function makeEl(tagName, attrs = {}) {
       while (node) { if (matches(node, sel)) return node; node = node.parentNode; }
       return null;
     },
+    // Node.contains — true for the node itself and any descendant. A DELEGATED
+    // listener guards on it (`!root.contains(el)`), so without this a test that
+    // dispatches on the section throws instead of exercising the handler.
+    contains(node) {
+      let n = node;
+      while (n) { if (n === this) return true; n = n.parentNode; }
+      return false;
+    },
     addEventListener(type, fn) { (this.listeners[type] = this.listeners[type] || []).push(fn); },
     focus() {},
     fire(type, event) { (this.listeners[type] || []).forEach((fn) => fn(event)); },