@bongos/core 1.19.714 → 1.19.724

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);

package/tests/claim_error_surface.mjs

@@ -13,8 +13,10 @@
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 
+import { readFileSync } from 'node:fs';
+
 const require = createRequire(import.meta.url);
-const { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan } = require('../scripts/gds/claim.js');
+const { formatClaimFailure, claimErrorInfo, goalMembershipOfferPlan, worktreeDetectionNote } = require('../scripts/gds/claim.js');
 
 let passed = 0;
 let failed = 0;
@@ -29,6 +31,12 @@ const envelope = (code, details = {}, message = code, status = 409) => ({
 });
 const text = (r) => r.lines.join('\n');
 
+// task 1002592 — populated by the guard test below, then checked against the
+// codes the server can actually refuse a claim with. Declared here so the drift
+// guard reads the SAME array the coverage test exercises rather than a second
+// hand-typed copy that could itself drift.
+const CLAIM_REFUSAL_CODES_UNDER_TEST = [];
+
 // The regression guard: no refusal may ever render a raw object.
 t('never dumps [object Object] for any known code', () => {
   const codes = [
@@ -37,8 +45,16 @@ t('never dumps [object Object] for any known code', () => {
     'newcomer_must_ship_first', 'ALREADY_CLAIMED', 'MODULE_CONFLICT',
     'TOUCHES_CONFLICT', 'TASK_NOT_READY', 'TASK_NOT_FOUND', 'DEPS_NOT_SHIPPED',
     'OPEN_BLOCKER', 'GOAL_MEMBERSHIP_REQUIRED',
+    // task 1002592: REBASE_REQUIRED was missing from this list for its whole
+    // life, which is exactly why its rendering gap survived — the guard that
+    // looked like it covered every refusal only covered the ones someone
+    // remembered to type. The drift guard at the bottom of this file now checks
+    // this array against what the server can actually throw.
+    'REBASE_REQUIRED', 'REWARD_REQUIRED', 'BUILDER_INACTIVE', 'INSUFFICIENT_RANK',
+    'XENOS_RESTRICTED', 'rank_too_low_for_task',
     'some_unmapped_future_code',
   ];
+  CLAIM_REFUSAL_CODES_UNDER_TEST.push(...codes);
   for (const c of codes) {
     const out = text(formatClaimFailure(envelope(c, { active_task_id: 5 }, 'msg'), 12));
     assert.ok(!out.includes('[object Object]'), `${c} produced a raw object dump`);
@@ -191,5 +207,151 @@ t('claimErrorInfo: reads envelope and flat shapes identically', () => {
   assert.equal(flat.code, 'X'); assert.equal(flat.d.a, 1);
 });
 
+// ---------------------------------------------------------------------------
+// task 1002592 — three measured defects in this surface.
+// ---------------------------------------------------------------------------
+
+// 1. REBASE_REQUIRED. ADR 0120 part 3's gate refuses EVERY new claim, so it is
+// the refusal a builder is most stuck behind, and it was the only one with no
+// branch: it printed `Claim failed (409) [REBASE_REQUIRED]: REBASE_REQUIRED.`
+// while a fully-formed remediation menu sat unread in the body.
+const REBASE_HINT = 'Your queue is gated: 1 confirmed task(s) await your rebase (task 1003575). Clear it with /strand-fix N (works on any machine), or rebase the branch and re-ship — /merge-mode only if this machine has a GitHub push credential.';
+
+t('REBASE_REQUIRED: names the owed tasks and relays the server hint', () => {
+  const out = text(formatClaimFailure(envelope('REBASE_REQUIRED', {
+    hint: REBASE_HINT,
+    rebaseTasks: [{ id: 1003575, title: 'The artist deploy gate', reason: 'strand:unresolvable_conflict:docs/module-api-changelog.md' }],
+  }), 1002592));
+  assert.match(out, /task 1003575/, 'must name the owed task id');
+  assert.match(out, /The artist deploy gate/, 'must name the owed task title');
+  assert.match(out, /strand:unresolvable_conflict/, 'must surface why it was flagged');
+  assert.match(out, /strand-fix/, 'must relay the hint, which leads with the universally-available exit');
+  // The regression proper: the old output was ONLY the bare code echo.
+  assert.ok(!/^Claim failed \(409\) \[REBASE_REQUIRED\]: REBASE_REQUIRED\.$/m.test(out),
+    'must not fall through to the bare code echo');
+});
+
+t('REBASE_REQUIRED: still guides when the server sends no hint and no task list', () => {
+  const out = text(formatClaimFailure(envelope('REBASE_REQUIRED', {}), 5));
+  assert.match(out, /gated/i, 'must say the queue is gated');
+  assert.match(out, /strand-fix|builder-release/, 'must name a way out even with an empty body');
+});
+
+t('REBASE_REQUIRED: server prose is clipped, flattened and capped before it hits the terminal', () => {
+  const out = text(formatClaimFailure(envelope('REBASE_REQUIRED', {
+    hint: 'H'.repeat(2000),
+    rebaseTasks: Array.from({ length: 50 }, (_, i) => ({
+      id: 1000 + i,
+      title: `T${'i'.repeat(400)}`,
+      reason: 'line oneline two\nline three',
+    })),
+  }), 5));
+  assert.ok(!//.test(out), 'escape sequences must never reach the terminal verbatim');
+  assert.ok(!/line one.*\n.*line two/.test(out), 'a multi-line reason must be flattened onto its own single line');
+  for (const line of out.split('\n')) {
+    assert.ok(line.length <= 620, `a rendered line ran to ${line.length} chars — the cap is not holding`);
+  }
+  const listed = out.split('\n').filter((l) => /^ {2}- task /.test(l)).length;
+  assert.ok(listed > 0 && listed <= 20, `expected a bounded task list, got ${listed} rows`);
+});
+
+// 2. The fallback floor. Any code the server sends a hint for must print it,
+// so the NEXT unmapped code cannot be mute the way REBASE_REQUIRED was.
+t('fallback: an unmapped code still prints the server hint when one is supplied', () => {
+  const out = text(formatClaimFailure(
+    envelope('some_future_gate', { hint: 'Do the thing, then retry.' }, 'nope', 409), 3));
+  assert.match(out, /some_future_gate/, 'still names the code');
+  assert.match(out, /Do the thing, then retry\./, 'and prints the way forward');
+});
+
+t('fallback: no hint means no invented guidance', () => {
+  const out = text(formatClaimFailure(envelope('some_future_gate', {}, 'nope', 409), 3));
+  assert.match(out, /some_future_gate/);
+  assert.ok(!/undefined/.test(out), 'must not print a stray undefined when no hint exists');
+});
+
+// 3. The original bug report: a failed worktree DETECTION arrives disguised as a
+// claim CONFLICT. The note must fire when null is WRONG and stay silent when
+// null is the correct answer — that distinction is the whole fix.
+t('worktreeDetectionNote: silent when the worktree WAS named (the refusal is genuine)', () => {
+  assert.deepEqual(worktreeDetectionNote({ worktree: 'task-42', isMainCheckout: false }, 42), []);
+});
+
+t('worktreeDetectionNote: silent in the MAIN CHECKOUT, where a null name is correct', () => {
+  assert.deepEqual(worktreeDetectionNote({ worktree: null, isMainCheckout: true }, 42), [],
+    'blaming path detection here would send the reader down exactly the wrong path');
+});
+
+t('worktreeDetectionNote: fires on a LINKED worktree with no name, and offers --worktree', () => {
+  const out = worktreeDetectionNote({ worktree: null, isMainCheckout: false }, 42).join('\n');
+  assert.match(out, /could not name its worktree/i);
+  assert.match(out, /linked worktree, so a name was expected/i, 'must say a name was expected here');
+  assert.match(out, /--worktree/, 'must print the explicit fallback');
+  assert.match(out, /claim\.js 42 --worktree/, 'the fallback must be runnable as printed');
+  assert.match(out, /not a claim conflict/i, 'must correct the misreading the report describes');
+});
+
+t('worktreeDetectionNote: fires when the tree kind is UNKNOWN, and hedges rather than asserts', () => {
+  const out = worktreeDetectionNote({ worktree: null, isMainCheckout: null }, 42).join('\n');
+  assert.match(out, /--worktree/);
+  assert.match(out, /not recognisable as the main checkout/i);
+  assert.ok(!/linked worktree, so a name was expected/i.test(out),
+    'must not claim this IS a linked worktree when the probe could not tell');
+});
+
+t('worktreeDetectionNote: a missing ctx is silent, never a crash', () => {
+  assert.deepEqual(worktreeDetectionNote(undefined, 42), []);
+  assert.deepEqual(worktreeDetectionNote({}, 42), [], 'an empty ctx knows nothing — say nothing');
+});
+
+t('session_already_has_active_claim: carries the detection note only when ctx warrants it', () => {
+  const e = envelope('session_already_has_active_claim', { active_task_id: 7, active_task_title: 'Other' });
+  const withNote = text(formatClaimFailure(e, 42, { worktree: null, isMainCheckout: false }));
+  assert.match(withNote, /--worktree/, 'an unnamed linked worktree must get the note');
+  const named = text(formatClaimFailure(e, 42, { worktree: 'task-42', isMainCheckout: false }));
+  assert.ok(!/--worktree/.test(named), 'a named worktree means the conflict is real — no note');
+  const mainCheckout = text(formatClaimFailure(e, 42, { worktree: null, isMainCheckout: true }));
+  assert.ok(!/--worktree/.test(mainCheckout), 'the main checkout must stay silent');
+  const noCtx = text(formatClaimFailure(e, 42));
+  assert.ok(!/--worktree/.test(noCtx), 'no ctx (every pre-existing caller) must behave as before');
+  assert.match(noCtx, /#7/, 'and must still render the original guidance');
+});
+
+// ---------------------------------------------------------------------------
+// The drift guard. REBASE_REQUIRED was thrown by the server and absent from the
+// coverage list above for its whole life, which is how a mute refusal survived a
+// test that looked like it covered every refusal. Derive the truth from the
+// server source instead of trusting a hand-typed array.
+//
+// A static scan fails SILENT — finding nothing looks identical to finding no
+// problem — so this asserts the extraction actually worked before it asserts
+// anything about the result.
+// ---------------------------------------------------------------------------
+t('drift guard: every code claimTask can throw is covered above (or consciously excluded)', () => {
+  const src = readFileSync(new URL('../modules/lifecycle/db-claims.js', import.meta.url), 'utf8');
+  const start = src.indexOf('async function claimTask');
+  assert.ok(start !== -1, 'could not find claimTask in db-claims.js — the guard is reading the wrong file');
+  const thrown = new Set(
+    [...src.slice(start).matchAll(/throw \{\s*code: '([A-Za-z_]+)'/g)].map((m) => m[1])
+  );
+
+  // Fail loudly on a scan that found nothing, and on one that lost its canary.
+  assert.ok(thrown.size >= 8, `extracted only ${thrown.size} codes — the regex has drifted off the source shape`);
+  assert.ok(thrown.has('REBASE_REQUIRED'), 'canary missing: the extraction is not seeing real throws');
+  assert.ok(thrown.has('TASK_NOT_FOUND'), 'canary missing: the extraction is not seeing real throws');
+
+  // Codes that exist on the claim path but can never reach the single-claim CLI.
+  // Listed explicitly so adding a server code forces a decision rather than
+  // silently widening this exemption.
+  const NOT_A_SINGLE_CLAIM_REFUSAL = new Set([
+    'BATCH_EMPTY', 'BATCH_DUPLICATE_IDS', 'BATCH_FAILED', // the hall's bulk-claim route
+  ]);
+
+  const covered = new Set(CLAIM_REFUSAL_CODES_UNDER_TEST);
+  const missing = [...thrown].filter((c) => !covered.has(c) && !NOT_A_SINGLE_CLAIM_REFUSAL.has(c));
+  assert.deepEqual(missing, [],
+    `these server codes are refusable but untested here — add them to the codes[] array above (or to NOT_A_SINGLE_CLAIM_REFUSAL with a reason): ${missing.join(', ')}`);
+});
+
 console.log(`\nclaim_error_surface: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);