@bongos/core 1.23.22 → 1.24.2

package/tests/bounded_rate_maps.mjs

@@ -0,0 +1,184 @@
+// tests/bounded_rate_maps.mjs
+//
+// Task 1004964 (2026-10-28 server audit, item 10): every in-memory rate-limit and
+// login map has a HARD size cap with oldest-first eviction, not only a time-based
+// sweep that runs every five minutes. Each case floods a map past its cap through
+// the real middleware (or the real tracker) and shows the size stays at the cap,
+// the newest entries survive, and the oldest are the ones evicted.
+// deviceFlows is also pruned on an unref'd timer, not only when a new flow starts.
+//
+// Hermetic: no DB, no network. Run:  node tests/bounded_rate_maps.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { test, summary } = makeRunner();
+
+const fakeRes = () => ({ set() { return this; }, fail() { return this; } });
+const noop = () => {};
+
+// Drive `mw` with `n` distinct callers; `reqFor(i)` builds the request for caller i.
+function flood(mw, n, reqFor) {
+  for (let i = 0; i < n; i++) mw(reqFor(i), fakeRes(), noop);
+}
+const byIp = (method = 'GET') => (i) => ({ method, ip: `ip-${i}`, headers: {}, path: '/' });
+const byBuilder = (i) => ({ method: 'GET', builder: { id: i }, headers: {} });
+
+// The one assertion every case makes: capped size, newest kept, oldest gone.
+function assertCapped(map, cap, n, keyFor) {
+  assert.ok(n > cap, 'the flood must overrun the cap');
+  assert.equal(map.size, cap, `map holds ${map.size}, cap is ${cap}`);
+  assert.ok(map.has(keyFor(n - 1)), 'the newest caller survives');
+  assert.ok(map.has(keyFor(n - cap)), 'the oldest still-in-cap caller survives');
+  assert.ok(!map.has(keyFor(n - cap - 1)), 'the caller just past the cap was evicted');
+  assert.ok(!map.has(keyFor(0)), 'the first caller was evicted');
+}
+
+const rl = require('../src/bongos/middleware/rate-limit.js');
+const CAP = rl.MAX_TRACKED_KEYS;
+const N = CAP + 25;
+
+await test('the shared cap is about 50k', () => {
+  assert.equal(CAP, 50000);
+});
+
+await test('rate-limit.js per-IP write bucket map stays capped', () => {
+  const m = rl._bucketMaps.ipBuckets;
+  m.clear();
+  flood(rl.rateLimitMiddleware, N, byIp('POST'));
+  assertCapped(m, CAP, N, (i) => `ip-${i}`);
+  m.clear();
+});
+
+await test('rate-limit.js per-session write bucket map stays capped', () => {
+  const m = rl._bucketMaps.sessionBuckets;
+  m.clear();
+  // A fresh IP per request: the per-IP check runs first and would 429 one IP early.
+  rl._bucketMaps.ipBuckets.clear();
+  flood(rl.rateLimitMiddleware, N, (i) => ({
+    method: 'POST', ip: `s-${i}`, headers: { authorization: `Bearer tok-${i}` },
+  }));
+  assertCapped(m, CAP, N, (i) => `b:tok-${i}`);
+  m.clear();
+  rl._bucketMaps.ipBuckets.clear();
+});
+
+await test('rate-limit.js public-read bucket map stays capped', () => {
+  const m = rl._bucketMaps.publicReadBuckets;
+  m.clear();
+  flood(rl.publicReadRateLimitMiddleware, N, byIp());
+  assertCapped(m, CAP, N, (i) => `ip-${i}`);
+  m.clear();
+});
+
+await test('rate-limit.js account-existence bucket map stays capped', () => {
+  const m = rl._bucketMaps.accountExistenceBuckets;
+  m.clear();
+  flood(rl.accountExistenceReadRateLimit, N, byIp());
+  assertCapped(m, CAP, N, (i) => `ip-${i}`);
+  m.clear();
+});
+
+await test('rate-limit.js public-project-feed bucket map stays capped', () => {
+  const m = rl._bucketMaps.projectFeedBuckets;
+  m.clear();
+  flood(rl.publicProjectFeedRateLimit, N, byIp());
+  assertCapped(m, CAP, N, (i) => `ip-${i}`);
+  m.clear();
+});
+
+await test('rate-limit.js default-read map keeps its tighter 10k cap', () => {
+  const m = rl._bucketMaps.defaultReadBuckets;
+  m.clear();
+  const mw = rl.defaultReadRateLimit({ stack: [] });
+  const cap = rl.DEFAULT_READ_MAX_TRACKED_IPS;
+  flood(mw, cap + 25, byIp());
+  assertCapped(m, cap, cap + 25, (i) => `ip-${i}`);
+  m.clear();
+});
+
+await test('memory sync + read bucket maps stay capped', () => {
+  const { _internals: mem } = require('../modules/memory/routes/memory.js');
+  assert.equal(mem.MAX_TRACKED_KEYS, CAP);
+  for (const [mw, map] of [[mem.syncRateLimit, mem.syncBuckets], [mem.readRateLimit, mem.readBuckets]]) {
+    map.clear();
+    flood(mw, N, byBuilder);
+    assertCapped(map, CAP, N, (i) => String(i));
+    map.clear();
+  }
+});
+
+await test('memory search bucket map stays capped', () => {
+  const { _internals: s } = require('../modules/memory/routes/search.js');
+  assert.equal(s.MAX_TRACKED_KEYS, CAP);
+  s.buckets.clear();
+  flood(s.searchRateLimit, N, byBuilder);
+  assertCapped(s.buckets, CAP, N, (i) => String(i));
+  s.buckets.clear();
+});
+
+await test('SSO applicant-read bucket map stays capped', () => {
+  const { _internals: sso } = require('../modules/platform-identity/routes/sso.js');
+  assert.equal(sso.APPLICANT_MAX_TRACKED_IPS, CAP);
+  sso.applicantReadBuckets.clear();
+  flood(sso.applicantReadRateLimit, N, byIp());
+  assertCapped(sso.applicantReadBuckets, CAP, N, (i) => `ip-${i}`);
+  sso.applicantReadBuckets.clear();
+});
+
+await test('public-profile bucket map stays capped', () => {
+  const { _internals: pp } = require('../modules/platform-identity/routes/public-profile.js');
+  assert.equal(pp.MAX_TRACKED_IPS, CAP);
+  pp.buckets.clear();
+  flood(pp.profileReadRateLimit, N, byIp());
+  assertCapped(pp.buckets, CAP, N, (i) => `ip-${i}`);
+  pp.buckets.clear();
+});
+
+await test('deviceFlows stays capped with oldest-first eviction', () => {
+  const ac = require('../src/bongos/auth-config.js');
+  assert.equal(ac.DEVICE_FLOW_MAX, CAP);
+  ac.deviceFlows.clear();
+  const live = () => ({ interval: 5, expires_at: Date.now() + 15 * 60_000, last_polled_at: 0 });
+  for (let i = 0; i < N; i++) ac.trackDeviceFlow(`dc-${i}`, live());
+  assertCapped(ac.deviceFlows, CAP, N, (i) => `dc-${i}`);
+  ac.deviceFlows.clear();
+});
+
+await test('deviceFlows is pruned on an unref\'d timer, not only on a new flow', () => {
+  // Load auth-config fresh with setInterval spied, to see the timer it arms.
+  const realSetInterval = globalThis.setInterval;
+  const armed = [];
+  globalThis.setInterval = (fn, ms, ...rest) => {
+    const t = realSetInterval(fn, ms, ...rest);
+    const unref = t.unref.bind(t);
+    const rec = { fn, ms, unrefd: false, t };
+    t.unref = () => { rec.unrefd = true; return unref(); };
+    armed.push(rec);
+    return t;
+  };
+  const key = require.resolve('../src/bongos/auth-config.js');
+  const cached = require.cache[key];
+  try {
+    delete require.cache[key];
+    const fresh = require('../src/bongos/auth-config.js');
+    const timer = armed.find((r) => r.fn === fresh.pruneDeviceFlows);
+    assert.ok(timer, 'a prune timer is armed at load');
+    assert.equal(timer.ms, fresh.DEVICE_FLOW_PRUNE_MS);
+    assert.ok(timer.ms >= 60_000, 'the prune timer is not a per-second wake');
+    assert.ok(timer.unrefd, 'the prune timer is unref\'d');
+    // And what it runs drops expired flows while keeping live ones, with no new flow started.
+    fresh.deviceFlows.set('old', { expires_at: Date.now() - 1 });
+    fresh.deviceFlows.set('new', { expires_at: Date.now() + 60_000 });
+    timer.fn();
+    assert.deepEqual([...fresh.deviceFlows.keys()], ['new']);
+  } finally {
+    globalThis.setInterval = realSetInterval;
+    for (const r of armed) clearInterval(r.t);
+    require.cache[key] = cached;
+  }
+});
+
+summary();

package/tests/claimable_blocker_status.mjs

@@ -35,7 +35,7 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const repoRoot = join(__dirname, '..');
 const read = (...p) => readFileSync(join(repoRoot, ...p), 'utf8');
 
-const MIG = 'core_264_claimable_respects_dependencies.sql';
+const MIG = 'core_285_task_needs.sql';
 const mig = read('migrations', MIG);
 // Comments carry the rationale; strip them when asserting on the executable body
 // so a claim in prose can never stand in for the real SQL.

package/tests/claims_batch_routes.mjs

@@ -0,0 +1,421 @@
+// tests/claims_batch_routes.mjs — the batch claim and batch release routes,
+// driven end to end through express and the error envelope (task 1004983;
+// gaps 2 and 15 of credit-burn/test-gap-hunt.md).
+//
+// Why this file exists. releaseClaimsBatch (modules/lifecycle/db-claims.js) was
+// named in no test, yet it is the one place a builder hands N claims back at
+// once: it sets each task to 'ready' and clears needs_rebase, and its `force`
+// flag skips the session check. The only thing that stops a builder releasing
+// SOMEONE ELSE's claim is its per-item ownership compare. POST /claims/batch
+// was never driven as a route either, so nothing pinned which gates sit in
+// front of it.
+//
+// How. The doorway (src/module-api.js) is stubbed in require.cache BEFORE the
+// route loads — db-claims.js destructures pool/withTx at require time, the
+// tests/access_requests_invite.mjs pattern. requireBuilder admits whichever
+// caller a test sets; withTx runs the REAL releaseClaimsBatch against a client
+// that records every query and answers the claims read from a fixture. For
+// POST /claims/batch the db facade's claimTasksBatch is swapped per test for a
+// recording handler (the route reads it at call time), so each documented error
+// can be thrown on demand.
+//
+// Every permission test asserts BOTH halves: the refusal, and that no write
+// query ran.
+//
+// Run:  node --test tests/claims_batch_routes.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after, beforeEach } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+
+const apiPath = require.resolve('../src/module-api.js');
+const realApi = require(apiPath);
+
+// ── the recording pool ───────────────────────────────────────────────────────
+
+let calls = [];          // every query any path ran: { sql, params, via }
+let claimFixture = [];   // rows the claims read answers with
+let activeClaims = [];   // rows getActiveClaimsForBuilder answers with
+let connects = 0;        // pool.connect() count — claimTasksBatch's tx door
+
+function answer(sql, params, via) {
+  calls.push({ sql, params, via });
+  // The release's locked read (FOR UPDATE) — distinct from the newcomer gate's
+  // active-claims read, which joins the same tables.
+  if (/FROM claims c JOIN tasks t ON t\.id = c\.task_id/.test(sql) && /FOR UPDATE/.test(sql)) {
+    const wanted = new Set(params[0].map(String));
+    return { rows: claimFixture.filter((r) => wanted.has(String(r.id))) };
+  }
+  if (/FROM claims c/.test(sql) && /released_at IS NULL/.test(sql)) {
+    return { rows: activeClaims };
+  }
+  return { rows: [], rowCount: 1 };
+}
+const client = {
+  async query(sql, params) { return answer(sql, params, 'tx'); },
+  release() {},
+};
+const pool = {
+  async query(sql, params) { return answer(sql, params, 'pool'); },
+  async connect() { connects += 1; return client; },
+};
+// Same shape as src/bongos/db-kernel.js withTx, on the recording client.
+async function withTx(fn) {
+  await client.query('BEGIN');
+  try {
+    const out = await fn(client);
+    await client.query('COMMIT');
+    return out;
+  } catch (err) {
+    await client.query('ROLLBACK');
+    throw err;
+  }
+}
+
+let caller = { id: '42', rank: 'thetes' };
+let callerSession = 'sess-A';
+function requireBuilder(req, _res, next) {
+  req.builder = { ...caller };
+  req.gdsSession = callerSession ? { session_id: callerSession } : undefined;
+  next();
+}
+
+require.cache[apiPath].exports = { ...realApi, pool, withTx, requireBuilder };
+
+const db = require('../modules/lifecycle/db.js');
+const realClaimTasksBatch = db.claimTasksBatch;
+const buildClaimsRouter = require('../modules/lifecycle/routes/claims.js');
+const { attachFail } = require('../src/bongos/middleware/error-envelope.js');
+
+const router = buildClaimsRouter();
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use('/api/bongos', router);
+
+let server, port;
+before(async () => {
+  server = http.createServer(app);
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  port = server.address().port;
+});
+after(async () => { await new Promise((r) => server.close(r)); });
+
+beforeEach(() => {
+  calls = []; claimFixture = []; activeClaims = []; connects = 0;
+  caller = { id: '42', rank: 'thetes' };
+  callerSession = 'sess-A';
+  db.claimTasksBatch = realClaimTasksBatch;
+});
+
+function post(pathname, body) {
+  return new Promise((resolve, reject) => {
+    const payload = JSON.stringify(body);
+    const req = http.request({
+      host: '127.0.0.1', port, path: pathname, method: 'POST',
+      headers: { 'content-type': 'application/json', 'content-length': Buffer.byteLength(payload) },
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => resolve({ status: res.statusCode, json: data ? JSON.parse(data) : null }));
+    });
+    req.on('error', reject);
+    req.write(payload);
+    req.end();
+  });
+}
+
+const RELEASE = '/api/bongos/claims/batch/release';
+const CLAIM = '/api/bongos/claims/batch';
+
+// Any statement that changes state. BEGIN/COMMIT and SELECTs are not writes.
+const isWrite = (c) => /^\s*(UPDATE|INSERT|DELETE)\b/i.test(c.sql);
+const writes = () => calls.filter(isWrite);
+const claimReleases = () => writes().filter((c) => /UPDATE claims SET released_at/.test(c.sql));
+const taskToReady = () => writes().filter((c) => /UPDATE tasks\s+SET status = 'ready'/.test(c.sql));
+
+// A claim row as the locked read returns it. node-pg hands bigint columns back
+// as strings, so the realistic default spells every id that way.
+const row = (over) => ({
+  id: '101', task_id: '501', builder_id: '42', released_at: null,
+  claimed_at: '2026-10-29T10:00:00Z', worktree_name: 'tree-a',
+  creator_session_id: 'sess-A', title: 'Own task', ...over,
+});
+
+// ── POST /claims/batch/release — the mixed batch ─────────────────────────────
+
+test('batch release [own, another builder\'s, own already-released, missing]: only the own open claim is released', async () => {
+  claimFixture = [
+    row({ id: '101', task_id: '501', title: 'Own task' }),
+    row({ id: '102', task_id: '502', builder_id: '7', creator_session_id: 'sess-Z', title: 'Their task' }),
+    row({ id: '103', task_id: '503', released_at: '2026-10-28T00:00:00Z', title: 'Old task' }),
+  ];
+  const r = await post(RELEASE, { claim_ids: [101, 102, 103, 999] });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.json.released, [{ claim_id: 101, task_id: '501', task_title: 'Own task' }]);
+  assert.deepEqual(r.json.failures, [
+    { claim_id: 102, reason: 'NOT_YOUR_CLAIM' },
+    { claim_id: 103, reason: 'ALREADY_RESOLVED' },
+    { claim_id: 999, reason: 'CLAIM_NOT_FOUND' },
+  ]);
+  // Exactly one claim closed and one task sent back to the queue — the own one.
+  assert.equal(claimReleases().length, 1);
+  assert.deepEqual(claimReleases()[0].params, [101]);
+  assert.equal(taskToReady().length, 1);
+  assert.deepEqual(taskToReady()[0].params, ['501']);
+  // Nothing at all was written about the other builder's claim or task.
+  for (const w of writes()) {
+    assert.ok(!w.params.map(String).some((p) => p === '102' || p === '502'),
+      `a write touched the other builder's claim or task: ${w.sql.trim().slice(0, 60)}`);
+  }
+});
+
+test('batch release of ONLY another builder\'s claim: refused, and no write query ran', async () => {
+  claimFixture = [row({ id: '102', task_id: '502', builder_id: '7', creator_session_id: 'sess-Z' })];
+  const r = await post(RELEASE, { claim_ids: [102] });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.json.released, []);
+  assert.deepEqual(r.json.failures, [{ claim_id: 102, reason: 'NOT_YOUR_CLAIM' }]);
+  assert.deepEqual(writes(), []);
+});
+
+test('force does not reach past ownership: another builder\'s claim with force:true is still refused, nothing written', async () => {
+  claimFixture = [row({ id: '102', task_id: '502', builder_id: '7', creator_session_id: 'sess-Z' })];
+  const r = await post(RELEASE, { claim_ids: [102], force: true });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.json.released, []);
+  assert.deepEqual(r.json.failures, [{ claim_id: 102, reason: 'NOT_YOUR_CLAIM' }]);
+  assert.deepEqual(writes(), []);
+});
+
+// ── the id-type matrix (node-pg bigint strings vs numbers) ────────────────────
+
+test('another builder\'s claim is refused whatever the id types — string or number on either side', async () => {
+  for (const [rowId, callerId] of [['7', '42'], ['7', 42], [7, '42'], [7, 42]]) {
+    calls = [];
+    caller = { id: callerId, rank: 'thetes' };
+    claimFixture = [row({ id: '102', task_id: '502', builder_id: rowId, creator_session_id: 'sess-Z' })];
+    const r = await post(RELEASE, { claim_ids: [102] });
+    assert.deepEqual(r.json.failures, [{ claim_id: 102, reason: 'NOT_YOUR_CLAIM' }],
+      `row builder_id ${JSON.stringify(rowId)} vs caller ${JSON.stringify(callerId)}`);
+    assert.deepEqual(writes(), []);
+  }
+});
+
+test('own claim with matching id types (both strings, as production sends them) is released', async () => {
+  caller = { id: '42', rank: 'thetes' };
+  claimFixture = [row({ builder_id: '42' }), row({ id: '102', task_id: '502', builder_id: '7', creator_session_id: 'sess-Z' })];
+  const r = await post(RELEASE, { claim_ids: [101, 102] });
+  assert.deepEqual(r.json.released.map((x) => x.claim_id), [101]);
+  assert.deepEqual(r.json.failures, [{ claim_id: 102, reason: 'NOT_YOUR_CLAIM' }]);
+  assert.equal(claimReleases().length, 1);
+});
+
+// KNOWN BUG (task 1005004, filed by task 1004983): releaseClaimsBatch compares
+// claim.builder_id !== builderId strictly, so a STRING row id (node-pg bigint)
+// against a NUMBER caller id refuses the caller's OWN claim as NOT_YOUR_CLAIM.
+// Production is unaffected today only because req.builder.id is also a string.
+// It fails closed (never releases a stranger's claim), so this pins CURRENT
+// behaviour; when the compare is fixed, flip this to expect a release.
+test('KNOWN BUG: own claim as string builder_id vs a NUMBER caller id is refused NOT_YOUR_CLAIM (fails closed)', async () => {
+  caller = { id: 42, rank: 'thetes' };
+  claimFixture = [row({ builder_id: '42' })];
+  const r = await post(RELEASE, { claim_ids: [101] });
+  assert.deepEqual(r.json.released, []);
+  assert.deepEqual(r.json.failures, [{ claim_id: 101, reason: 'NOT_YOUR_CLAIM' }]);
+  assert.deepEqual(writes(), []);
+});
+
+// ── the session check, and force ─────────────────────────────────────────────
+
+test('own claim bound to a different session, without force: CLAIM_SESSION_MISMATCH, nothing written', async () => {
+  callerSession = 'sess-A';
+  claimFixture = [row({ creator_session_id: 'sess-B', worktree_name: 'tree-b' })];
+  const r = await post(RELEASE, { claim_ids: [101] });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.json.released, []);
+  assert.deepEqual(r.json.failures, [{ claim_id: 101, reason: 'CLAIM_SESSION_MISMATCH', claimWorktree: 'tree-b' }]);
+  assert.deepEqual(writes(), []);
+});
+
+test('own claim bound to a different session, WITH force: released', async () => {
+  callerSession = 'sess-A';
+  claimFixture = [row({ creator_session_id: 'sess-B', worktree_name: 'tree-b' })];
+  const r = await post(RELEASE, { claim_ids: [101], force: true });
+  assert.equal(r.status, 200);
+  assert.deepEqual(r.json.released.map((x) => x.claim_id), [101]);
+  assert.deepEqual(r.json.failures, []);
+  assert.equal(claimReleases().length, 1);
+  assert.equal(taskToReady().length, 1);
+});
+
+test('force must be the boolean true: a truthy string is refused by validation before any query', async () => {
+  claimFixture = [row({ creator_session_id: 'sess-B' })];
+  const r = await post(RELEASE, { claim_ids: [101], force: 'yes' });
+  assert.equal(r.status, 400);
+  assert.deepEqual(calls, []);
+});
+
+test('a released task goes back to ready with needs_rebase cleared, and the session log is sealed as abandoned', async () => {
+  claimFixture = [row()];
+  await post(RELEASE, { claim_ids: [101] });
+  const ready = taskToReady()[0];
+  assert.match(ready.sql, /needs_rebase = false/);
+  assert.match(ready.sql, /needs_rebase_reason = NULL/);
+  assert.match(claimReleases()[0].sql, /outcome = 'abandoned'/);
+  const seal = writes().find((c) => /INSERT INTO session_logs/.test(c.sql));
+  assert.ok(seal, 'session log sealed');
+  assert.equal(seal.params[0], '42', 'sealed under the caller, never a caller-supplied id');
+  assert.equal(seal.params[4], 'abandoned');
+  // All of it inside one transaction.
+  assert.equal(calls[0].sql, 'BEGIN');
+  assert.equal(calls[calls.length - 1].sql, 'COMMIT');
+});
+
+// ── the release body ──────────────────────────────────────────────────────────
+
+test('release body: an empty array → 400 claim_ids_required, no query', async () => {
+  const r = await post(RELEASE, { claim_ids: [] });
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'claim_ids_required');
+  assert.deepEqual(calls, []);
+});
+
+test('release body: 21 ids → 400, no query', async () => {
+  const r = await post(RELEASE, { claim_ids: Array.from({ length: 21 }, (_, i) => i + 1) });
+  assert.equal(r.status, 400);
+  assert.deepEqual(calls, []);
+});
+
+test('release body: 20 ids is allowed through to the release', async () => {
+  const r = await post(RELEASE, { claim_ids: Array.from({ length: 20 }, (_, i) => i + 1) });
+  assert.equal(r.status, 200);
+  assert.equal(r.json.failures.length, 20);
+});
+
+test('release body: non-numeric ids → 400 claim_ids_must_be_numbers, no query', async () => {
+  const r = await post(RELEASE, { claim_ids: [101, 'abc'] });
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'claim_ids_must_be_numbers');
+  assert.deepEqual(calls, []);
+});
+
+test('release body: claim_ids missing → 400, no query', async () => {
+  const r = await post(RELEASE, {});
+  assert.equal(r.status, 400);
+  assert.deepEqual(calls, []);
+});
+
+// ── POST /claims/batch — the middleware chain ────────────────────────────────
+
+function chainFor(path) {
+  const layer = router.stack.find((l) => l.route && l.route.path === path && l.route.methods.post);
+  assert.ok(layer, `POST ${path} is mounted`);
+  return layer.route.stack.map((s) => s.handle.name || '<handler>');
+}
+
+test('POST /claims/batch middleware chain is pinned: requireBuilder → gateNewcomerClaim → handler', () => {
+  assert.deepEqual(chainFor('/claims/batch'), ['requireBuilder', 'gateNewcomerClaim', '<handler>']);
+});
+
+test('POST /claims carries the one-claim-per-session gate that POST /claims/batch does not (the documented difference)', () => {
+  const single = chainFor('/claims');
+  assert.ok(single.includes('gateOneActiveClaimPerSession'));
+  assert.ok(single.includes('gateNewcomerClaim'));
+  assert.ok(!chainFor('/claims/batch').includes('gateOneActiveClaimPerSession'),
+    'if batch claim gains the session gate, update this pin (task 1005005 asks whether it should)');
+});
+
+test('POST /claims/batch/release middleware chain is pinned: requireBuilder → handler', () => {
+  assert.deepEqual(chainFor('/claims/batch/release'), ['requireBuilder', '<handler>']);
+});
+
+// ── POST /claims/batch — the newcomer gate ───────────────────────────────────
+
+test('a xenos with a claim in flight is refused by gateNewcomerClaim: 403, and no claim or write is attempted', async () => {
+  caller = { id: '42', rank: 'xenos' };
+  activeClaims = [{ claim_id: '88', task_id: '700', title: 'First task' }];
+  let batchCalls = 0;
+  db.claimTasksBatch = async () => { batchCalls += 1; return { claims: [] }; };
+  const r = await post(CLAIM, { task_ids: [501, 502] });
+  assert.equal(r.status, 403);
+  assert.equal(r.json.error.code, 'newcomer_must_ship_first');
+  assert.equal(r.json.error.details.active_task_id, '700');
+  assert.equal(batchCalls, 0, 'claimTasksBatch never ran');
+  assert.equal(connects, 0, 'no transaction was opened');
+  assert.deepEqual(writes(), []);
+  assert.equal(calls.length, 1, 'only the gate\'s own active-claims read');
+});
+
+test('a thetes with a claim in flight is NOT held by the newcomer gate — and makes no gate lookup', async () => {
+  caller = { id: '42', rank: 'thetes' };
+  activeClaims = [{ claim_id: '88', task_id: '700', title: 'First task' }];
+  let batchCalls = 0;
+  db.claimTasksBatch = async () => { batchCalls += 1; return { claims: [] }; };
+  const r = await post(CLAIM, { task_ids: [501] });
+  assert.equal(r.status, 201);
+  assert.equal(batchCalls, 1);
+  assert.deepEqual(calls, []);
+});
+
+// ── POST /claims/batch — each documented error maps to its status and body ────
+
+test('success: 201 with the claims, ids coerced to numbers, caller and session from the server', async () => {
+  let seen;
+  db.claimTasksBatch = async (args) => { seen = args; return { claims: [{ id: 1, task_id: 501 }] }; };
+  const r = await post(CLAIM, { task_ids: ['501', 502], worktree_name: 'wt' });
+  assert.equal(r.status, 201);
+  assert.deepEqual(r.json.claims, [{ id: 1, task_id: 501 }]);
+  assert.deepEqual(seen, { taskIds: [501, 502], builderId: '42', worktreePrefix: 'wt', creatorSessionId: 'sess-A' });
+});
+
+test('bind_session:false claims session-unbound', async () => {
+  let seen;
+  db.claimTasksBatch = async (args) => { seen = args; return { claims: [] }; };
+  await post(CLAIM, { task_ids: [501], bind_session: false });
+  assert.equal(seen.creatorSessionId, null);
+});
+
+const ERROR_MAP = [
+  ['BATCH_FAILED', 409, 'batch_failed'],
+  ['BATCH_EMPTY', 400, 'task_ids_required'],
+  ['BATCH_DUPLICATE_IDS', 400, 'duplicate_task_ids'],
+  ['BUILDER_INACTIVE', 403, 'BUILDER_INACTIVE'],
+];
+for (const [thrown, status, code] of ERROR_MAP) {
+  test(`claimTasksBatch throws ${thrown} → ${status} ${code}`, async () => {
+    const failures = [{ task_id: 501, reason: 'ALREADY_CLAIMED' }];
+    db.claimTasksBatch = async () => { throw { code: thrown, failures }; };
+    const r = await post(CLAIM, { task_ids: [501] });
+    assert.equal(r.status, status);
+    assert.equal(r.json.error.code, code);
+    if (thrown === 'BATCH_FAILED') assert.deepEqual(r.json.error.details, { failures });
+  });
+}
+
+test('an unexpected error → 500 batch_claim_failed with no internals in the message', async () => {
+  db.claimTasksBatch = async () => { throw new Error('connection refused at 10.0.0.1'); };
+  const r = await post(CLAIM, { task_ids: [501] });
+  assert.equal(r.status, 500);
+  assert.equal(r.json.error.code, 'batch_claim_failed');
+  assert.equal(r.json.error.message, 'internal error');
+});
+
+test('claim body: empty → 400 task_ids_required, 21 ids → 400, non-numeric → 400 task_ids_must_be_numbers; never reaches claimTasksBatch', async () => {
+  let batchCalls = 0;
+  db.claimTasksBatch = async () => { batchCalls += 1; return { claims: [] }; };
+  const empty = await post(CLAIM, { task_ids: [] });
+  assert.equal(empty.status, 400);
+  assert.equal(empty.json.error.code, 'task_ids_required');
+  const big = await post(CLAIM, { task_ids: Array.from({ length: 21 }, (_, i) => i + 1) });
+  assert.equal(big.status, 400);
+  const bad = await post(CLAIM, { task_ids: [1, 'x'] });
+  assert.equal(bad.status, 400);
+  assert.equal(bad.json.error.code, 'task_ids_must_be_numbers');
+  assert.equal(batchCalls, 0);
+  assert.deepEqual(calls, []);
+});