@bongos/core 1.19.715 → 1.19.724

package/tests/artist_gate_release.mjs

@@ -0,0 +1,283 @@
+// tests/artist_gate_release.mjs
+//
+// THE ESCAPE HATCH (task 1003575, ADR 0241 §3) — releasing a deploy that an
+// unresolved artist review is holding.
+//
+// ADR 0241 was explicit that this must be the mechanism that already exists —
+// the override request — and NOT a second authority path. So a release is the
+// same table, the same request flow and the same decide endpoint as the grader
+// bypass, and everything worth pinning here is where the two DIVERGE:
+//
+//   • a release may be opened on a task that is NOT 'completed'. An artist review
+//     sits at `backlog`, and ADR 0241 guard #4 calls a strict project with no
+//     artist "the normal case" for a new instance — so a completed-only gate
+//     would make the one documented hatch unusable for exactly the case it was
+//     written for. (This is what the first cut of this task got wrong.)
+//   • only the PROJECT OWNER may decide it — narrower than the grader bypass's
+//     Archon floor, and enforced in the data layer so no second caller inherits
+//     the wider one.
+//   • approving it CONFIRMS NOTHING and PAYS NOTHING. The review stays open on
+//     the board; what stops is its hold on the pin.
+//   • it is never quiet: a self-release is permitted (a solo project would
+//     otherwise deadlock) and recorded as a self-override.
+//
+// DB-free: decideOverrideRequest's #538 `deps.pool` seam drives the txn with a
+// SQL-aware fake, and the module pool is stubbed on the doorway for the reads.
+//
+// Run:  node --test tests/artist_gate_release.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+
+// The reward port must be registered before decideOverrideRequest is driven
+// (the grader-bypass branch resolves it) — the override_attribution.mjs setup.
+const achievements = require('../modules/economy/achievements.js');
+achievements.evaluateAfterShip = async () => [];
+achievements.evaluateAfterCreditAward = async () => [];
+achievements.evaluateAfterClaim = async () => [];
+achievements.reconcileBuilderAchievements = async () => [];
+const seams = require('../src/module-seams.js');
+if (!seams.hasProvider('reward')) seams.registerProvider('reward', require('../modules/economy/reward.js'));
+
+const api = require('../src/module-api.js');
+
+// The module-level pool createOverrideRequest reads through. Stubbed BEFORE the
+// db facade is required, because db-overrides.js destructures it at load.
+let poolRows = [];
+let poolQueries = [];
+api.pool = { query: async (sql, params) => { poolQueries.push({ sql, params }); return { rows: poolRows }; } };
+
+const db = require('../modules/lifecycle/db.js');
+const overrides = require('../modules/lifecycle/db-overrides.js');
+
+const { test, summary } = makeRunner();
+
+const OWNER = 7;
+const ARCHON = 42;
+const ARTIST = 99;
+
+const review = (over = {}) => ({
+  id: 9001, status: 'backlog', source: 'cascade',
+  source_ref: 'cascade-artist-review-on-ship-7001', merged_into_task_id: null, ...over,
+});
+const ordinary = (over = {}) => ({ id: 555, status: 'backlog', source: 'manual', source_ref: null, merged_into_task_id: null, ...over });
+
+const flat = (q) => String(q.sql).replace(/\s+/g, ' ').trim();
+const find = (queries, re) => queries.find((q) => re.test(flat(q)));
+const all = (queries, re) => queries.filter((q) => re.test(flat(q)));
+
+// =========================================================================
+// Which tasks are in the release class
+// =========================================================================
+
+await test('the release class is exactly "an artist review that is still open" — asked of core\'s one reader', () => {
+  assert.equal(overrides.gateReleaseTarget(review()), true);
+  // Resolved reviews are not held, so there is nothing to release.
+  assert.equal(overrides.gateReleaseTarget(review({ status: 'shipped' })), false);
+  assert.equal(overrides.gateReleaseTarget(review({ status: 'abandoned' })), false);
+  assert.equal(overrides.gateReleaseTarget(review({ merged_into_task_id: 9100 })), false);
+  // And an ordinary task never is — a release must not become a second way to
+  // wave a graded ship through at any status.
+  assert.equal(overrides.gateReleaseTarget(ordinary()), false);
+  assert.equal(overrides.gateReleaseTarget(ordinary({ status: 'completed' })), false);
+});
+
+// =========================================================================
+// Opening one
+// =========================================================================
+
+await test('a request MAY be opened on a backlog artist review — the case the hatch exists for', async () => {
+  poolRows = [review()]; poolQueries = [];
+  // The INSERT returns the created row; the fake answers every statement with
+  // poolRows, which is enough to prove the completed-check did not refuse.
+  const row = await db.createOverrideRequest({ taskId: 9001, requesterId: ARTIST, rationale: 'x'.repeat(30) });
+  assert.ok(row, 'the request was created rather than refused');
+  assert.ok(find(poolQueries, /^INSERT INTO task_override_requests/), 'it reached the insert');
+});
+
+await test('an ordinary task at backlog is STILL refused — the class is narrow, not an open door', async () => {
+  poolRows = [ordinary()]; poolQueries = [];
+  await assert.rejects(
+    () => db.createOverrideRequest({ taskId: 555, requesterId: ARTIST, rationale: 'x'.repeat(30) }),
+    (e) => e.code === 'TASK_NOT_COMPLETED' && e.currentStatus === 'backlog'
+  );
+  assert.equal(all(poolQueries, /^INSERT INTO task_override_requests/).length, 0, 'nothing was written');
+});
+
+await test('a RESOLVED artist review is refused too — a dismissed review holds nothing to release', async () => {
+  poolRows = [review({ status: 'shipped' })]; poolQueries = [];
+  await assert.rejects(
+    () => db.createOverrideRequest({ taskId: 9001, requesterId: ARTIST, rationale: 'x'.repeat(30) }),
+    (e) => e.code === 'TASK_NOT_COMPLETED'
+  );
+});
+
+// =========================================================================
+// Deciding one
+// =========================================================================
+
+// The txn fake: answers the target-task SELECT with `target`, the request UPDATE
+// with an approved row, and everything else with nothing.
+function txPool({ target, requesterId = ARTIST, decision = 'approve' }) {
+  return makeSqlAwareClient((s) => {
+    if (/FROM tasks WHERE id = \(SELECT task_id/.test(s)) return { rows: target ? [target] : [] };
+    if (/^UPDATE task_override_requests/.test(s)) {
+      return { rows: [{ id: 1, task_id: target ? target.id : 0, status: decision === 'approve' ? 'approved' : 'denied', requested_by_builder_id: requesterId }] };
+    }
+    if (/^UPDATE tasks/.test(s)) return { rows: [{ id: target.id, title: 't', credits_reward: 10, kind: 'feature' }] };
+    return { rows: [] };
+  });
+}
+
+const owner = async () => ({ id: OWNER });
+
+await test('an ARCHON who is not the owner cannot release — and the refusal costs the review nothing', async () => {
+  const pool = txPool({ target: review() });
+  await assert.rejects(
+    () => db.decideOverrideRequest(
+      { requestId: 1, archonId: ARCHON, decision: 'approve' },
+      { pool, getFoundingBuilder: owner, insertAuditLog: async () => {} }
+    ),
+    (e) => e.code === 'OVERRIDE_OWNER_ONLY'
+  );
+  assert.equal(all(pool._client.queries, /^UPDATE task_override_requests/).length, 0, 'the request stays open');
+  assert.ok(find(pool._client.queries, /^ROLLBACK/), 'and the txn rolls back');
+});
+
+await test('the OWNER releases it — and the release confirms nothing and pays nothing', async () => {
+  const audits = [];
+  const pool = txPool({ target: review() });
+  const out = await db.decideOverrideRequest(
+    { requestId: 1, archonId: OWNER, decision: 'approve' },
+    { pool, getFoundingBuilder: owner, insertAuditLog: async (a) => { audits.push(a); } }
+  );
+
+  assert.equal(out.request.status, 'approved');
+  assert.equal(out.gateRelease.taskId, '9001');
+  // The three things a grader bypass does that a release must NOT.
+  assert.equal(out.confirmResult, null, 'no confirm result — nothing was confirmed');
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0, 'the review is NOT flipped to confirmed');
+  assert.equal(all(pool._client.queries, /INSERT INTO credit_log/).length, 0, 'and nothing is paid for work nobody did');
+  assert.ok(find(pool._client.queries, /^COMMIT/), 'the release commits');
+});
+
+await test('a SELF-release is permitted and is recorded as a self-override — never quiet (ADR 0241 §3)', async () => {
+  const audits = [];
+  const pool = txPool({ target: review(), requesterId: OWNER });
+  const out = await db.decideOverrideRequest(
+    { requestId: 1, archonId: OWNER, decision: 'approve' },
+    { pool, getFoundingBuilder: owner, insertAuditLog: async (a) => { audits.push(a); } }
+  );
+  // Permitted: a solo instance where the owner is also the builder and the artist
+  // would otherwise deadlock, which ADR 0241 §3 rules out explicitly.
+  assert.equal(out.gateRelease.selfOverride, true);
+  assert.equal(audits.length, 1, 'exactly one audit line for the act');
+  assert.equal(audits[0].builderId, OWNER);
+  assert.equal(audits[0].requestBodyRedacted.override_kind, 'artist_gate_release');
+  assert.equal(audits[0].requestBodyRedacted.self_override, true, 'the ledger says WHO waved through their OWN work');
+  assert.equal(audits[0].requestBodyRedacted.task_id, '9001');
+});
+
+await test('a release of SOMEONE ELSE\'S review is audited too, and marked as not a self-override', async () => {
+  const audits = [];
+  const pool = txPool({ target: review(), requesterId: ARTIST });
+  const out = await db.decideOverrideRequest(
+    { requestId: 1, archonId: OWNER, decision: 'approve' },
+    { pool, getFoundingBuilder: owner, insertAuditLog: async (a) => { audits.push(a); } }
+  );
+  assert.equal(out.gateRelease.selfOverride, false);
+  assert.equal(audits.length, 1, 'every release is on the record, self or not');
+});
+
+await test('an audit write that FAILS does not roll back a decision the owner made', async () => {
+  const pool = txPool({ target: review() });
+  const out = await db.decideOverrideRequest(
+    { requestId: 1, archonId: OWNER, decision: 'approve' },
+    { pool, getFoundingBuilder: owner, insertAuditLog: async () => { throw new Error('audit table down'); } }
+  );
+  assert.equal(out.request.status, 'approved', 'the release is durable in the request row');
+  assert.ok(find(pool._client.queries, /^COMMIT/));
+});
+
+await test('DENYING a release changes nothing — the review goes on holding the pin', async () => {
+  const pool = txPool({ target: review(), decision: 'deny' });
+  const out = await db.decideOverrideRequest(
+    { requestId: 1, archonId: OWNER, decision: 'deny' },
+    { pool, getFoundingBuilder: owner, insertAuditLog: async () => {} }
+  );
+  assert.equal(out.request.status, 'denied');
+  assert.equal(out.gateRelease, null, 'nothing was released');
+  assert.equal(all(pool._client.queries, /^UPDATE tasks/).length, 0);
+});
+
+await test('the GRADER BYPASS is untouched: a completed ordinary task still needs only an Archon', async () => {
+  // The owner check must not have leaked onto the path it does not belong to —
+  // that would be a silent tightening of an unrelated authority.
+  const pool = txPool({ target: ordinary({ status: 'completed' }) });
+  const out = await db.decideOverrideRequest(
+    { requestId: 1, archonId: ARCHON, decision: 'approve' },
+    { pool, getFoundingBuilder: owner, insertAuditLog: async () => {} }
+  );
+  assert.equal(out.gateRelease, null, 'not a release');
+  assert.ok(out.confirmResult, 'the ordinary bypass still confirms');
+  assert.ok(find(pool._client.queries, /^UPDATE tasks/), 'and still flips the task');
+});
+
+// =========================================================================
+// The gate READS the release
+// =========================================================================
+
+await test('an approved override is excluded by the gate\'s own read — a released review stops holding', async () => {
+  poolRows = []; poolQueries = [];
+  await db.listOpenArtistReviews({ source: 'cascade', refPrefix: 'cascade-artist-review-on-ship-', resolvedStatuses: ['shipped', 'abandoned'] });
+  const q = flat(poolQueries[0]);
+  // The exclusion has to be IN THE QUERY: the release is not a status change, so
+  // nothing downstream would notice it otherwise — which is precisely how the
+  // first cut of this task shipped an escape hatch that released nothing.
+  assert.match(q, /NOT EXISTS \( SELECT 1 FROM task_override_requests r WHERE r\.task_id = t\.id AND r\.status = 'approved'\)/);
+  assert.deepEqual(poolQueries[0].params.slice(0, 3), ['cascade', 'cascade-artist-review-on-ship-%', ['shipped', 'abandoned']]);
+});
+
+await test('the scan asks for ONE row past its cap, so "there are more" needs no second COUNT', async () => {
+  poolRows = []; poolQueries = [];
+  const out = await db.listOpenArtistReviews({ source: 'cascade', refPrefix: 'p-', resolvedStatuses: [], limit: 3 });
+  assert.equal(poolQueries[0].params[3], 4, 'cap + 1');
+  assert.deepEqual(out, { reviews: [], truncated: false });
+
+  // With cap+1 rows back, the extra one is dropped and truncation is declared —
+  // a COUNT that could disagree with the page it describes is what this avoids.
+  poolRows = [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }]; poolQueries = [];
+  const full = await db.listOpenArtistReviews({ source: 'cascade', refPrefix: 'p-', resolvedStatuses: [], limit: 3 });
+  assert.equal(full.reviews.length, 3);
+  assert.equal(full.truncated, true);
+});
+
+await test('the owner-check seam is NODE_ENV-gated like deps.pool — it cannot be swapped in production', () => {
+  // The one check deciding who may release a deploy-blocking review must not be
+  // overridable by an options object that happens to carry the key: a batch decide
+  // path or a careless options-forwarding refactor would otherwise hand an
+  // attacker-shaped `{ getFoundingBuilder: () => me }` straight past the gate.
+  //
+  // Asserted on the RESOLVER rather than through decideOverrideRequest, because
+  // the deps.pool seam is gated the same way — so a "production" run of the whole
+  // function fails on a real database connection long before it reaches this
+  // check, and a test that passed on THAT would be proving nothing.
+  const injected = async () => ({ id: ARCHON });
+  const doorway = api.getFoundingBuilder;
+
+  assert.equal(overrides.resolveOwnerReader({ getFoundingBuilder: injected }, { NODE_ENV: 'test' }), injected,
+    'a test keeps its seam');
+  for (const NODE_ENV of ['production', 'development', undefined]) {
+    assert.equal(overrides.resolveOwnerReader({ getFoundingBuilder: injected }, { NODE_ENV }), doorway,
+      `NODE_ENV=${NODE_ENV}: the injected reader is ignored and the doorway decides`);
+  }
+  // And with nothing injected it is the doorway either way.
+  assert.equal(overrides.resolveOwnerReader({}, { NODE_ENV: 'test' }), doorway);
+});
+
+summary();

package/tests/artist_gate_route.mjs

@@ -0,0 +1,174 @@
+// tests/artist_gate_route.mjs
+//
+// GET /artist-gate — the one read the deploy consults (ADR 0241, task 1003575).
+//
+// The pure verdict logic is pinned in tests/artist_gate.mjs; what is worth pinning
+// HERE is the wiring, and specifically the three things a route can get wrong in a
+// way no pure test would see:
+//
+//   • 'off' must not even ASK the board. At `off` no reviews are filed, so a query
+//     would be a per-deploy read that can only ever return rows the gate ignores.
+//   • the DB read must be handed the CASCADE's own (source, ref) spelling, not a
+//     second copy of it — a drifted prefix silently matches nothing, and a gate
+//     that finds nothing looks exactly like a gate that is satisfied.
+//   • `holds` and `halt` must agree. Two fields describing one fact is two chances
+//     to disagree, and the caller trusts whichever it read.
+//
+// DB-free: the data-access fn is stubbed on the cached module object (the
+// provisioning_settings.mjs pattern).
+//
+// Run:  node --test tests/artist_gate_route.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import http from 'node:http';
+
+const require = createRequire(import.meta.url);
+
+const db = require('../modules/lifecycle/db.js');
+const api = require('../src/module-api.js');
+const gateModule = require('../src/bongos/artist-gate.js');
+
+let rows = [];
+let scanTruncated = false;
+let queries = [];
+db.listOpenArtistReviews = async (opts) => { queries.push(opts); return { reviews: rows, truncated: scanTruncated }; };
+
+let mode = 'strict';
+let since = null;
+api.requireBuilder = (req, _res, next) => { 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 };
+
+const express = require('express');
+const buildRouter = require('../modules/lifecycle/routes/artist-gate.js');
+const app = express();
+app.use((_req, res, next) => {
+  res.fail = (code, opts) => res.status((opts && opts.status) || 400).json({ error: { code } });
+  next();
+});
+app.use('/api/bongos', buildRouter());
+
+const server = app.listen(0);
+await new Promise((r) => server.once('listening', r));
+const base = `http://127.0.0.1:${server.address().port}/api/bongos`;
+
+function get(path) {
+  return new Promise((resolve, reject) => {
+    http.get(`${base}${path}`, (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, headers: res.headers, raw: d }); });
+    }).on('error', reject);
+  });
+}
+
+const review = (over = {}) => ({
+  id: '9001', title: 'Artist review: the copy and visuals that shipped in task 7001',
+  status: 'backlog', source: 'cascade', source_ref: 'cascade-artist-review-on-ship-7001',
+  created_at: '2026-09-12T00:00:00.000Z', merged_into_task_id: null, ...over,
+});
+
+function reset({ level = 'strict', cutoff = null, open = [], truncated = false } = {}) {
+  mode = level; since = cutoff; rows = open; scanTruncated = truncated; queries = [];
+}
+
+test("at 'off' the board is never asked — nothing is filed, so there is nothing to read", async () => {
+  reset({ level: 'off', open: [review()] });
+  const r = await get('/artist-gate');
+  assert.equal(r.status, 200, r.raw);
+  assert.equal(r.body.mode, 'off');
+  assert.equal(r.body.holds, false);
+  assert.deepEqual(r.body.reviews, []);
+  assert.equal(queries.length, 0, 'a per-deploy query whose rows are ignored is a query that should not run');
+});
+
+test('the DB read is handed the cascade\'s OWN source and ref prefix, never a second copy', async () => {
+  reset({ open: [] });
+  await get('/artist-gate');
+  assert.equal(queries.length, 1);
+  assert.equal(queries[0].source, gateModule.ARTIST_REVIEW_SOURCE);
+  assert.equal(queries[0].refPrefix, gateModule.ARTIST_REVIEW_REF_PREFIX);
+  assert.deepEqual(queries[0].resolvedStatuses, gateModule.RESOLVED_REVIEW_STATUSES);
+});
+
+test("at 'strict' an open review is reported as holding, with the refusal already composed", async () => {
+  reset({ open: [review()] });
+  const r = await get('/artist-gate');
+  assert.equal(r.body.mode, 'strict');
+  assert.equal(r.body.holds, true);
+  assert.deepEqual(r.body.reviews.map((t) => t.id), ['9001']);
+  assert.equal(r.body.halt.code, 'ARTIST_REVIEW_UNRESOLVED');
+  assert.match(r.body.halt.detail, /override-request/, 'the caller must not have to invent the way out');
+});
+
+test("at 'advisory' the same open review is reported but holds nothing", async () => {
+  reset({ level: 'advisory', open: [review()] });
+  const r = await get('/artist-gate');
+  assert.equal(r.body.holds, false);
+  assert.equal(r.body.halt, null);
+  assert.deepEqual(r.body.reviews.map((t) => t.id), ['9001'], 'advisory still SHOWS the queue — it just does not stop');
+});
+
+test('the cutoff is applied to what the board returned (ADR 0241 §5)', async () => {
+  reset({ cutoff: '2026-09-11T00:00:00.000Z', open: [review({ id: '9001', created_at: '2026-09-01T00:00:00.000Z' }), review({ id: '9002' })] });
+  const r = await get('/artist-gate');
+  assert.deepEqual(r.body.reviews.map((t) => t.id), ['9002'], 'the pre-raise review is not this gate\'s business');
+  assert.equal(r.body.since, '2026-09-11T00:00:00.000Z', 'and the cutoff itself is reported, so the answer is checkable');
+});
+
+test('`holds` and `halt` can never disagree', async () => {
+  for (const open of [[], [review()]]) {
+    for (const level of ['off', 'advisory', 'strict']) {
+      reset({ level, open });
+      const r = await get('/artist-gate');
+      assert.equal(r.body.holds, r.body.halt !== null, `${level} / ${open.length} open`);
+    }
+  }
+});
+
+test('the payload carries NO task title — the one untrusted string it could have carried', async () => {
+  reset({ open: [review()] });
+  const r = await get('/artist-gate');
+  assert.deepEqual(Object.keys(r.body.reviews[0]).sort(), ['created_at', 'id']);
+  assert.doesNotMatch(r.raw, /Artist review: the copy/, 'builder-written board text never reaches this wire');
+});
+
+test('a capped scan reports a FLOOR, not a census — the verdict is unchanged either way', async () => {
+  reset({ open: [review({ id: '9001' }), review({ id: '9002' })], truncated: true });
+  const r = await get('/artist-gate');
+  assert.equal(r.body.truncated, true, 'the caller must never read the list as "and that is all"');
+  assert.equal(r.body.holds, true, 'truncation cannot weaken the gate — every row returned is a holder');
+  assert.match(r.body.halt.message, /^2\+ unresolved artist reviews/);
+});
+
+test('truncation is DROPPED when the cutoff shortened the page — "200+" over three rows is the worse lie', async () => {
+  reset({
+    cutoff: '2026-09-11T00:00:00.000Z',
+    open: [review({ id: '9001', created_at: '2026-09-01T00:00:00.000Z' }), review({ id: '9002' })],
+    truncated: true,
+  });
+  const r = await get('/artist-gate');
+  assert.equal(r.body.truncated, false);
+  assert.match(r.body.halt.message, /^1 unresolved artist review /);
+});
+
+test('the read is never cached — a dismissed review must free the deploy immediately', async () => {
+  reset({ open: [review()] });
+  const r = await get('/artist-gate');
+  assert.equal(r.headers['cache-control'], 'no-store');
+});
+
+test('a database failure is a 500 with no internals, never a quiet "nothing holds"', async () => {
+  reset({ open: [] });
+  db.listOpenArtistReviews = async () => { throw new Error('relation "tasks" does not exist'); };
+  const r = await get('/artist-gate');
+  assert.equal(r.status, 500);
+  assert.equal(r.body.error.code, 'artist_gate_read_failed');
+  assert.doesNotMatch(r.raw, /relation/, 'the error text never reaches the wire');
+  db.listOpenArtistReviews = async (opts) => { queries.push(opts); return { reviews: rows, truncated: scanTruncated }; };
+});
+
+test.after(() => server.close());

package/tests/box_scope_predicate.mjs

@@ -0,0 +1,117 @@
+// tests/box_scope_predicate.mjs
+//
+// task 1002593 — "is this a box-scope refusal?" must have exactly ONE definition,
+// and it must survive the error-envelope shape.
+//
+// THE BUG THIS PINS. A box-scoped session (ADR 0053) may call only the dev-box
+// bootstrap endpoints; everything else answers 403 box_scope. Callers branched on
+// `res.data.error === 'box_scope'`. Then routes moved to the object error envelope
+// (ADR 0116) — `data.error` became `{ code, message, details }` — and every one of
+// those comparisons silently became dead code. Nothing failed; the branch just
+// stopped firing, and builders got the generic 403 path instead of the guided
+// re-auth the branch existed to give them. Task 1002162 fixed it in cli-lib by
+// adding isBoxScope(); scripts/gds/ship-land.js was the last site still deciding
+// for itself, and task 1002593 repointed it.
+//
+// WHY A DRIFT GUARD AND NOT JUST UNIT CASES. The original defect was not a wrong
+// answer — it was a comparison that could never be true. A unit test of the good
+// predicate cannot see a second, dead one somewhere else in the tree; only a scan
+// can. So the last test here is the one that actually protects against a repeat.
+//
+// Run:  node tests/box_scope_predicate.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const CLI_DIR = path.join(ROOT, 'scripts', 'gds');
+const { isBoxScope } = require(path.join(CLI_DIR, 'cli-lib.js'));
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const ENVELOPE = { status: 403, data: { error: { code: 'box_scope', message: 'box-scoped session' } } };
+const LEGACY = { status: 403, data: { error: 'box_scope' } };
+
+t('fires for the CURRENT object error envelope — the shape that killed the old comparison', () => {
+  assert.equal(isBoxScope(ENVELOPE), true);
+});
+
+t('the old hand-rolled comparison is provably dead against that same shape', () => {
+  // Not a tautology: this is the regression itself. If someone reintroduces
+  // `data.error === 'box_scope'` anywhere, this is what it evaluates to.
+  assert.equal(ENVELOPE.data.error === 'box_scope', false,
+    'the envelope shape must NOT satisfy a bare string comparison — that is the whole defect');
+});
+
+t('still fires for the LEGACY flat shape, so a pinned older core keeps working', () => {
+  assert.equal(isBoxScope(LEGACY), true);
+});
+
+t('does not fire on a different code at 403', () => {
+  assert.equal(isBoxScope({ status: 403, data: { error: { code: 'rank_too_low_for_task' } } }), false);
+  assert.equal(isBoxScope({ status: 403, data: { error: 'forbidden' } }), false);
+});
+
+t('does not fire on a non-403, even carrying the code', () => {
+  assert.equal(isBoxScope({ status: 200, data: { error: { code: 'box_scope' } } }), false,
+    'status is part of the contract — a 200 mentioning box_scope is not a refusal');
+  assert.equal(isBoxScope({ status: 500, data: { error: { code: 'box_scope' } } }), false);
+});
+
+t('tolerates missing/!odd bodies instead of throwing', () => {
+  for (const bad of [undefined, null, {}, { status: 403 }, { status: 403, data: null }, { status: 403, data: {} }]) {
+    assert.equal(isBoxScope(bad), false, `${JSON.stringify(bad)} must be a quiet false, not a throw`);
+  }
+  assert.equal(isBoxScope({ status: 403, data: { error: null } }), false,
+    'a null error must not be read as an envelope');
+});
+
+// ---------------------------------------------------------------------------
+// The drift guard. One definition, and no second opinion anywhere in the CLI.
+// ---------------------------------------------------------------------------
+t('no CLI script decides box-scope for itself — cli-lib owns the predicate', () => {
+  const files = fs.readdirSync(CLI_DIR).filter((f) => f.endsWith('.js'));
+  // Fail loudly on a scan that found nothing: an empty sweep looks exactly like a
+  // clean one, and a guard that silently stops scanning protects nothing.
+  assert.ok(files.length > 20, `only ${files.length} scripts scanned — the sweep is not reading the CLI directory`);
+
+  const offenders = [];
+  let sawTheCanary = false;
+  for (const f of files) {
+    const src = fs.readFileSync(path.join(CLI_DIR, f), 'utf8');
+    if (f === 'cli-lib.js') {
+      // The one legitimate definition. Confirms the scan can actually see the
+      // pattern it is looking for, so a regex that has drifted off the source
+      // shape reports as a failure here rather than as a clean sweep everywhere.
+      sawTheCanary = /===\s*'box_scope'/.test(src);
+      continue;
+    }
+    // Strip comments: several files DISCUSS the old comparison on purpose.
+    const code = src.replace(/\/\*[\s\S]*?\*\//g, '').replace(/\/\/[^\n]*/g, '');
+    for (const m of code.matchAll(/[^\n]*===\s*'box_scope'[^\n]*/g)) {
+      offenders.push(`${f}: ${m[0].trim()}`);
+    }
+  }
+
+  assert.ok(sawTheCanary, 'cli-lib.js no longer contains the comparison — this guard is looking for the wrong pattern');
+  assert.deepEqual(offenders, [],
+    `these sites decide box-scope themselves instead of calling isBoxScope(); that is how the comparison died last time:\n  ${offenders.join('\n  ')}`);
+});
+
+t('ship-land.js — the site task 1002593 repointed — uses the shared predicate', () => {
+  const src = fs.readFileSync(path.join(CLI_DIR, 'ship-land.js'), 'utf8');
+  assert.match(src, /isBoxScope\s*\(/, 'the box-scope branch must call the shared predicate');
+  assert.match(src, /require\('\.\/cli-lib'\)/, 'and import it from cli-lib rather than redefining it');
+});
+
+console.log(`\nbox_scope_predicate: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);