@bongos/core 1.17.0

package/tests/merge_lock.mjs

@@ -0,0 +1,312 @@
+// Tests for src/bongos/merge-lock.js — the shared advisory mutex that serializes
+// the single main worktree across ship.js's auto-merge AND the /merge-mode CLI
+// (V3.R50 / #269, criterion C6). Before #269 the lock lived inside ship.js and
+// only covered ship-vs-ship; these tests pin the cross-surface behavior:
+// auto-vs-auto, stale reclaim, manual time-based holds, and ownership-guarded
+// release.
+//
+// Run: node tests/merge_lock.mjs
+
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const lock = require('../modules/lifecycle/merge-lock.js');
+
+const tests = [];
+const test = (name, fn) => tests.push({ name, fn });
+
+// Build a throwaway repo-root with a .git dir so lockPath has somewhere to write.
+function tmpRoot() {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-mergelock-'));
+  fs.mkdirSync(path.join(dir, '.git'));
+  return dir;
+}
+function cleanup(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
+}
+
+// ---- lockPath ----
+
+test('lockPath: lives under .git/', () => {
+  assert.equal(lock.lockPath('/repo'), path.join('/repo', '.git', 'otb-automerge.lock'));
+});
+
+// ---- acquire / readLock ----
+
+test('acquire: writes pid/ts/mode and readLock parses it', () => {
+  const root = tmpRoot();
+  try {
+    assert.equal(lock.acquire(root, { pid: 4242, mode: 'auto' }), true);
+    const rec = lock.readLock(root);
+    assert.equal(rec.pid, 4242);
+    assert.equal(rec.mode, 'auto');
+    assert.ok(rec.ts > 0);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('acquire: second auto-acquire by a LIVE holder fails fast (waitMs=0)', () => {
+  const root = tmpRoot();
+  try {
+    // Hold with our own (alive) pid so the liveness check keeps the lock held.
+    assert.equal(lock.acquire(root, { pid: process.pid, mode: 'auto' }), true);
+    let slept = 0;
+    const ok = lock.acquire(root, { pid: process.pid, mode: 'auto', waitMs: 0, sleep: () => { slept++; } });
+    assert.equal(ok, false, 'should not acquire while a live holder owns it');
+    assert.equal(slept, 0, 'waitMs=0 should not sleep');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('acquire: reclaims a lock held by a DEAD pid (auto mode) and recovers the worktree', () => {
+  const root = tmpRoot();
+  try {
+    // Plant a lock owned by a pid that is certainly dead.
+    fs.writeFileSync(lock.lockPath(root), `999999\n${Date.now()}\nauto\n`);
+    let recovered = 0;
+    const ok = lock.acquire(root, { pid: process.pid, mode: 'auto', waitMs: 0, recover: () => { recovered++; } });
+    assert.equal(ok, true, 'dead-pid auto lock must be reclaimed');
+    assert.equal(lock.readLock(root).pid, process.pid);
+    assert.equal(recovered, 1, 'reclaiming a stale lock must trigger worktree recovery exactly once');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('acquire: reclaims an auto lock whose stamp is older than AUTO_STALE_MS', () => {
+  const root = tmpRoot();
+  try {
+    const old = Date.now() - lock.AUTO_STALE_MS - 1000;
+    // Use a LIVE pid so only the time-based staleness can justify reclaim.
+    fs.writeFileSync(lock.lockPath(root), `${process.pid}\n${old}\nauto\n`);
+    assert.equal(lock.acquire(root, { pid: process.pid, waitMs: 0, recover: () => {} }), true);
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('acquire: a LIVE holder is NOT reclaimed → recovery does NOT run', () => {
+  const root = tmpRoot();
+  try {
+    lock.acquire(root, { pid: process.pid, mode: 'auto' }); // alive holder
+    let recovered = 0;
+    const ok = lock.acquire(root, { pid: process.pid, mode: 'auto', waitMs: 0, recover: () => { recovered++; } });
+    assert.equal(ok, false, 'should not acquire while a live holder owns it');
+    assert.equal(recovered, 0, 'must never touch a live holder’s worktree');
+  } finally {
+    cleanup(root);
+  }
+});
+
+// ---- manual holds (the /merge-mode CLI case) ----
+
+test('manual hold: NOT reclaimed by dead pid within the manual window', () => {
+  const root = tmpRoot();
+  try {
+    // Manual hold writes pid=0 (CLI process already exited). A fresh manual
+    // hold must block an auto acquirer even though pid 0 is "not alive".
+    fs.writeFileSync(lock.lockPath(root), `0\n${Date.now()}\nmanual\n`);
+    const rec = lock.readLock(root);
+    assert.equal(rec.mode, 'manual');
+    assert.equal(lock.isStale(rec), false, 'fresh manual hold is not stale');
+    const ok = lock.acquire(root, { pid: process.pid, mode: 'auto', waitMs: 0 });
+    assert.equal(ok, false, 'auto acquirer must wait behind a live manual hold');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('manual hold: reclaimed only after MANUAL_STALE_MS (longer than auto)', () => {
+  const root = tmpRoot();
+  try {
+    // Older than the AUTO window but younger than the MANUAL window → still held.
+    const age = Date.now() - lock.AUTO_STALE_MS - 1000;
+    fs.writeFileSync(lock.lockPath(root), `0\n${age}\nmanual\n`);
+    assert.equal(lock.isStale(lock.readLock(root)), false, 'manual hold survives the auto window');
+
+    // Older than the MANUAL window → reclaimable.
+    const veryOld = Date.now() - lock.MANUAL_STALE_MS - 1000;
+    fs.writeFileSync(lock.lockPath(root), `0\n${veryOld}\nmanual\n`);
+    assert.equal(lock.isStale(lock.readLock(root)), true, 'manual hold reclaims after its window');
+  } finally {
+    cleanup(root);
+  }
+});
+
+// ---- back-compat with the pre-#269 two-line lockfile ----
+
+test('readLock: two-line legacy lockfile (pid\\nts) reads as mode=auto', () => {
+  const root = tmpRoot();
+  try {
+    fs.writeFileSync(lock.lockPath(root), `${process.pid}\n${Date.now()}\n`);
+    const rec = lock.readLock(root);
+    assert.equal(rec.mode, 'auto', 'missing mode line defaults to auto');
+    assert.equal(rec.pid, process.pid);
+  } finally {
+    cleanup(root);
+  }
+});
+
+// ---- release ----
+
+test('release: owner can remove its own auto lock', () => {
+  const root = tmpRoot();
+  try {
+    lock.acquire(root, { pid: process.pid, mode: 'auto' });
+    lock.release(root, { pid: process.pid });
+    assert.equal(lock.readLock(root), null, 'lock file should be gone');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('release: a non-owner does NOT remove someone else’s live auto lock', () => {
+  const root = tmpRoot();
+  try {
+    // Lock owned by a different (live) pid — process.pid stands in as "us".
+    fs.writeFileSync(lock.lockPath(root), `12345\n${Date.now()}\nauto\n`);
+    lock.release(root, { pid: process.pid }); // we are NOT 12345
+    assert.notEqual(lock.readLock(root), null, 'must not steal another auto holder’s lock');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('release: anyone can release a manual hold (CLI acquirer != releaser)', () => {
+  const root = tmpRoot();
+  try {
+    fs.writeFileSync(lock.lockPath(root), `0\n${Date.now()}\nmanual\n`);
+    lock.release(root, { pid: process.pid });
+    assert.equal(lock.readLock(root), null, 'manual hold released by a different process');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('release: force removes any lock', () => {
+  const root = tmpRoot();
+  try {
+    fs.writeFileSync(lock.lockPath(root), `12345\n${Date.now()}\nauto\n`);
+    lock.release(root, { pid: process.pid, force: true });
+    assert.equal(lock.readLock(root), null, 'force release removes a foreign lock');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('release: no-op when no lock exists', () => {
+  const root = tmpRoot();
+  try {
+    lock.release(root, { pid: process.pid }); // must not throw
+    assert.equal(lock.readLock(root), null);
+  } finally {
+    cleanup(root);
+  }
+});
+
+// ---- recoverWorktree (the crash/stale-reclaim self-heal) ----
+
+// A fake git that records commands and simulates MERGE_HEAD / dirty state
+// without touching a real repo.
+function mockGit({ mergeHead = false, dirty = false } = {}) {
+  const calls = [];
+  const runner = (cmd) => {
+    calls.push(cmd);
+    if (cmd.includes('rev-parse -q --verify MERGE_HEAD')) {
+      if (mergeHead) return 'deadbeefdeadbeef\n';
+      throw new Error('fatal: needed a single revision'); // not mid-merge
+    }
+    if (cmd.includes('status --porcelain')) return dirty ? ' M scripts/x.js\n' : '';
+    return ''; // merge --abort / fetch / reset --hard
+  };
+  return { runner, calls };
+}
+
+test('recoverWorktree: removes an OLD orphaned index.lock', () => {
+  const root = tmpRoot();
+  try {
+    const lk = path.join(root, '.git', 'index.lock');
+    fs.writeFileSync(lk, 'orphan');
+    const { runner } = mockGit();
+    // Make the just-written lock look older than the grace window via the clock.
+    lock.recoverWorktree(root, { now: () => Date.now() + lock.INDEX_LOCK_GRACE_MS + 5000, runner });
+    assert.equal(fs.existsSync(lk), false, 'a stale orphaned index.lock must be cleared');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('recoverWorktree: leaves a FRESH index.lock untouched (could be a live op)', () => {
+  const root = tmpRoot();
+  try {
+    const lk = path.join(root, '.git', 'index.lock');
+    fs.writeFileSync(lk, 'maybe-live');
+    const { runner } = mockGit();
+    lock.recoverWorktree(root, { now: Date.now, runner }); // fresh file
+    assert.equal(fs.existsSync(lk), true, 'a fresh index.lock must be left for the possibly-live owner');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('recoverWorktree: mid-merge → abort + fetch + reset', () => {
+  const root = tmpRoot();
+  try {
+    const { runner, calls } = mockGit({ mergeHead: true });
+    lock.recoverWorktree(root, { runner });
+    assert.ok(calls.some((c) => c.includes('merge --abort')), 'must abort the half-merge');
+    assert.ok(calls.some((c) => c.includes('fetch origin main')), 'must refresh origin/main');
+    assert.ok(calls.some((c) => c.includes('reset --hard origin/main')), 'must reset to origin/main');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('recoverWorktree: dirty-but-not-mid-merge → reset, no abort', () => {
+  const root = tmpRoot();
+  try {
+    const { runner, calls } = mockGit({ dirty: true });
+    lock.recoverWorktree(root, { runner });
+    assert.ok(!calls.some((c) => c.includes('merge --abort')), 'no merge to abort');
+    assert.ok(calls.some((c) => c.includes('reset --hard origin/main')), 'still resets a dirty tree');
+  } finally {
+    cleanup(root);
+  }
+});
+
+test('recoverWorktree: clean reclaim → no churn (no abort, no reset)', () => {
+  const root = tmpRoot();
+  try {
+    const { runner, calls } = mockGit({ mergeHead: false, dirty: false });
+    lock.recoverWorktree(root, { runner });
+    assert.ok(!calls.some((c) => c.includes('merge --abort')), 'nothing to abort on a clean reclaim');
+    assert.ok(!calls.some((c) => c.includes('reset --hard')), 'must not reset a clean tree gratuitously');
+  } finally {
+    cleanup(root);
+  }
+});
+
+// ---- runner ----
+
+let pass = 0;
+let fail = 0;
+for (const { name, fn } of tests) {
+  try {
+    await fn();
+    console.log(`PASS  ${name}`);
+    pass++;
+  } catch (e) {
+    console.log(`FAIL  ${name}`);
+    console.log(`      ${e.message}`);
+    if (process.env.VERBOSE) console.log(e.stack);
+    fail++;
+  }
+}
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/tests/metrics.mjs

@@ -0,0 +1,147 @@
+// tests/metrics.mjs
+//
+// Unit coverage for the zero-dependency Prometheus exporter (task #1680,
+// V4.R28a) — src/bongos/metrics.js. No DB or network: collectDbGauges/render are
+// driven with a fake pg client, and the HTTP middleware with a fake req/res.
+//
+// Run:  node tests/metrics.mjs
+
+import { strict as assert } from 'node:assert';
+import { EventEmitter } from 'node:events';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const metrics = require('../src/bongos/metrics.js');
+
+const { test, summary } = makeRunner();
+
+// A fake pg client answering the four queries collectDbGauges runs.
+const fakePool = {
+  async query(sql) {
+    const s = sql.replace(/\s+/g, ' ');
+    if (/FROM tasks GROUP BY status/.test(s)) {
+      return { rows: [{ status: 'shipped', n: 5 }, { status: 'ready', n: 2 }] };
+    }
+    if (/FROM claims/.test(s)) return { rows: [{ total: 10, active: 1 }] };
+    if (/FROM builders GROUP BY rank/.test(s)) return { rows: [{ rank: 'metic', n: 3 }] };
+    if (/WHERE b\.status = 'active'/.test(s)) {
+      return { rows: [{ github_login: 'jaxri', credits: 2022, shipped: 7 }] };
+    }
+    return { rows: [] };
+  },
+};
+
+function fakeReq({ path = '/', method = 'GET', remote = '127.0.0.1', headers = {} } = {}) {
+  const lower = {};
+  for (const k of Object.keys(headers)) lower[k.toLowerCase()] = headers[k];
+  return { path, method, socket: { remoteAddress: remote }, get: (h) => lower[h.toLowerCase()] };
+}
+
+await test('normalizeRoute collapses ids/uuids/hashes to bounded templates', () => {
+  assert.equal(metrics.normalizeRoute('/'), '/');
+  assert.equal(metrics.normalizeRoute('/api/gds/tasks/1380'), '/api/gds/tasks/:id');
+  assert.equal(metrics.normalizeRoute('/api/gds/claims/9999/resolve'), '/api/gds/claims/:id/resolve');
+  assert.equal(
+    metrics.normalizeRoute('/x/123e4567-e89b-12d3-a456-426614174000'),
+    '/x/:uuid'
+  );
+  assert.equal(metrics.normalizeRoute('/assets/atlas-89d47b50abcd'), '/assets/:hash');
+  // two different ids share ONE series (the whole point — cardinality bound)
+  assert.equal(metrics.normalizeRoute('/api/gds/tasks/1'), metrics.normalizeRoute('/api/gds/tasks/2'));
+});
+
+await test('incCounter accumulates per label-set and renders counter format', async () => {
+  metrics.__resetForTests();
+  metrics.incCounter('gds_http_requests_total', 'h', { method: 'GET', route: '/x', status: '200' });
+  metrics.incCounter('gds_http_requests_total', 'h', { method: 'GET', route: '/x', status: '200' });
+  metrics.incCounter('gds_http_requests_total', 'h', { method: 'GET', route: '/x', status: '500' });
+  const out = await metrics.render(fakePool);
+  assert.match(out, /# TYPE gds_http_requests_total counter/);
+  assert.match(out, /gds_http_requests_total\{method="GET",route="\/x",status="200"\} 2/);
+  assert.match(out, /gds_http_requests_total\{method="GET",route="\/x",status="500"\} 1/);
+});
+
+await test('observeHistogram emits cumulative _bucket/_sum/_count', async () => {
+  metrics.__resetForTests();
+  metrics.observeHistogram('gds_http_request_duration_seconds', 'd', { method: 'GET', route: '/x' }, 0.02);
+  metrics.observeHistogram('gds_http_request_duration_seconds', 'd', { method: 'GET', route: '/x' }, 3.0);
+  const out = await metrics.render(fakePool);
+  assert.match(out, /# TYPE gds_http_request_duration_seconds histogram/);
+  assert.match(out, /gds_http_request_duration_seconds_count\{method="GET",route="\/x"\} 2/);
+  assert.match(out, /gds_http_request_duration_seconds_bucket\{method="GET",route="\/x",le="\+Inf"\} 2/);
+  // 0.02 falls in le=0.025; only 1 obs <= 0.025
+  assert.match(out, /gds_http_request_duration_seconds_bucket\{method="GET",route="\/x",le="0.025"\} 1/);
+});
+
+await test('httpMiddleware records request + duration + auth-failure on res finish', async () => {
+  metrics.__resetForTests();
+  const mw = metrics.httpMiddleware();
+
+  // a 200 on a templated route
+  let req = fakeReq({ path: '/api/gds/tasks/1380', method: 'GET' });
+  let res = new EventEmitter(); res.statusCode = 200;
+  let called = false; mw(req, res, () => { called = true; });
+  assert.ok(called, 'middleware calls next()');
+  res.emit('finish');
+
+  // a 401 → also bumps auth_failures
+  req = fakeReq({ path: '/api/gds/me', method: 'GET' });
+  res = new EventEmitter(); res.statusCode = 401;
+  mw(req, res, () => {}); res.emit('finish');
+
+  // /metrics + /healthz are NOT counted (noise)
+  req = fakeReq({ path: '/metrics' }); res = new EventEmitter(); res.statusCode = 200;
+  mw(req, res, () => {}); res.emit('finish');
+
+  const out = await metrics.render(fakePool);
+  assert.match(out, /gds_http_requests_total\{method="GET",route="\/api\/gds\/tasks\/:id",status="200"\} 1/);
+  assert.match(out, /gds_auth_failures_total\{code="401"\} 1/);
+  assert.doesNotMatch(out, /route="\/metrics"/, '/metrics scrape is not self-counted');
+});
+
+await test('authorizeScrape: local Prometheus yes, public no, bearer token yes', () => {
+  // loopback, no proxy header → allowed (the local agent)
+  assert.equal(metrics.authorizeScrape(fakeReq({ remote: '127.0.0.1' })), true);
+  assert.equal(metrics.authorizeScrape(fakeReq({ remote: '::1' })), true);
+  // public via Caddy sets X-Forwarded-For → denied
+  assert.equal(
+    metrics.authorizeScrape(fakeReq({ remote: '127.0.0.1', headers: { 'x-forwarded-for': '203.0.113.7' } })),
+    false
+  );
+  // a non-loopback origin → denied
+  assert.equal(metrics.authorizeScrape(fakeReq({ remote: '10.0.0.5' })), false);
+  // bearer token path (remote, with XFF) → allowed only with the right token
+  process.env.METRICS_TOKEN = 'sekret';
+  assert.equal(
+    metrics.authorizeScrape(fakeReq({ remote: '10.0.0.5', headers: { authorization: 'Bearer sekret', 'x-forwarded-for': '203.0.113.7' } })),
+    true
+  );
+  assert.equal(
+    metrics.authorizeScrape(fakeReq({ remote: '10.0.0.5', headers: { authorization: 'Bearer wrong' } })),
+    false
+  );
+  delete process.env.METRICS_TOKEN;
+});
+
+await test('collectDbGauges renders build/auth gauges from the pool', async () => {
+  const out = await metrics.collectDbGauges(fakePool);
+  assert.match(out, /# TYPE gds_tasks gauge/);
+  assert.match(out, /gds_tasks\{status="shipped"\} 5/);
+  assert.match(out, /gds_claims_total\{?\}? ?10/);
+  assert.match(out, /gds_claims_active.* 1/);
+  assert.match(out, /gds_builders\{rank="metic"\} 3/);
+  assert.match(out, /gds_builder_shipped_tasks\{builder="jaxri"\} 7/);
+  assert.match(out, /gds_builder_credits\{builder="jaxri"\} 2022/);
+});
+
+await test('render is resilient: a DB failure still yields process metrics + db_scrape_ok 0', async () => {
+  metrics.__resetForTests();
+  const brokenPool = { async query() { throw new Error('db down'); } };
+  const out = await metrics.render(brokenPool);
+  assert.match(out, /gds_process_uptime_seconds/);
+  assert.match(out, /gds_build_info\{version=".*",node=".*"\} 1/);
+  assert.match(out, /gds_db_scrape_ok\{?\}? ?0/);
+});
+
+summary();

package/tests/migration_allocation.mjs

@@ -0,0 +1,146 @@
+// tests/migration_allocation.mjs
+//
+// Coverage for touches[] cleanup [1/8] (task 876, migration 081): the claim-time
+// migration-number allocator must key off the tasks.needs_migration boolean, NOT
+// the literal string 'migrations/' inside the touches[] array.
+//
+// Why this matters: duplicate migration numbers merge cleanly into main and are
+// NOT detectable at merge time (two branches each adding migrations/082_*.sql
+// just coexist). So the allocation trigger is load-bearing and must not ride on
+// a free-text path array that drifts as code wanders. This test pins:
+//
+//   1. Migration 081 adds the column, backfills it from the retiring sentinel,
+//      and re-bases the counter floor (the convention every migration follows).
+//   2. db.js (single + batch claim) selects needs_migration and allocates off
+//      the boolean — and NO LONGER triggers allocation off touches.includes.
+//   3. POST /tasks sets needsMigration from the keyword regex and stops
+//      injecting 'migrations/' into touches[].
+//   4. A simulation of the trigger logic proves the cutover: needs_migration is
+//      the only signal — a task with 'migrations/' in touches[] but the boolean
+//      false does NOT get a number.
+//
+// No live DB — the allocator's trigger is a pure predicate, reproduced in JS.
+//
+// Run:  node tests/migration_allocation.mjs
+
+import { strict as assert } from 'node:assert';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try {
+    await fn();
+    console.log(`  ok  ${name}`);
+    passed++;
+  } catch (err) {
+    console.error(`  FAIL ${name}`);
+    console.error('    ', err.message);
+    failed++;
+  }
+}
+
+const read = (...p) => readFileSync(join(repoRoot, ...p), 'utf8');
+const migrationSql = read('migrations', '081_tasks_needs_migration.sql');
+// the tasks db slice + the tasks route carved to modules/lifecycle/ at BV1.R86.
+const dbSrc = read('modules', 'lifecycle', 'db.js');
+const routesSrc = read('modules', 'lifecycle', 'routes', 'tasks.js');
+const captureSrc = read('scripts', 'gds', 'capture.js');
+
+// The allocator's trigger, reproduced as a pure predicate. This is the exact
+// condition both claimTask and batchClaim now branch on.
+function shouldReserveMigrationNumber(task) {
+  return task.needs_migration === true;
+}
+
+(async () => {
+  await test('migration 081 adds needs_migration boolean (default false)', () => {
+    assert.ok(
+      /ADD\s+COLUMN\s+IF\s+NOT\s+EXISTS\s+needs_migration\s+boolean\s+NOT\s+NULL\s+DEFAULT\s+false/i.test(migrationSql),
+      'migration 081 must add tasks.needs_migration boolean NOT NULL DEFAULT false'
+    );
+  });
+
+  await test('migration 081 backfills needs_migration from the retiring touches[] sentinel', () => {
+    assert.ok(
+      /UPDATE\s+tasks[\s\S]*SET\s+needs_migration\s*=\s*true[\s\S]*'migrations\/'\s*=\s*ANY\s*\(\s*touches\s*\)/i.test(migrationSql),
+      "migration 081 must backfill needs_migration=true where 'migrations/' = ANY(touches)"
+    );
+  });
+
+  await test('migration 081 re-bases the migration counter floor (>= 82)', () => {
+    assert.ok(
+      /UPDATE\s+migration_counter\s+SET\s+next_number\s*=\s*GREATEST\(next_number,\s*82\)/i.test(migrationSql),
+      'migration 081 must bump migration_counter.next_number to >= 82 (this file is 081)'
+    );
+  });
+
+  await test('db.js claim SELECTs load needs_migration (single + batch)', () => {
+    // Tolerant of columns appended after needs_migration (e.g. module_key, BV1.R53)
+    // — the test's intent is that BOTH claim-path SELECTs still load needs_migration,
+    // not that the column list is frozen. [\w, ]* matches any trailing columns.
+    const selects = dbSrc.match(/SELECT id, status, touches, newcomer_friendly, requires_rank, needs_migration[\w, ]* FROM tasks/g) || [];
+    assert.equal(
+      selects.length, 2,
+      `both claim-path SELECTs must load needs_migration; found ${selects.length} (expected 2: claimTask + batchClaim)`
+    );
+  });
+
+  await test('db.js allocates off the needs_migration boolean (single + batch)', () => {
+    const single = /if \(task\.needs_migration === true\)/.test(dbSrc);
+    const batch = /if \(t\.needs_migration === true\)/.test(dbSrc);
+    assert.ok(single, 'claimTask must reserve a number when task.needs_migration === true');
+    assert.ok(batch, 'batchClaim must reserve a number when t.needs_migration === true');
+  });
+
+  await test('db.js no longer triggers allocation off touches.includes("migrations/")', () => {
+    // The string remains a legal touches[] entry (conductor coverage etc.); what
+    // must be gone is using it as the migration-RESERVATION trigger.
+    assert.ok(
+      !/includes\('migrations\/'\)/.test(dbSrc),
+      "db.js must not key migration allocation off touches.includes('migrations/')"
+    );
+  });
+
+  await test('POST /tasks sets needsMigration from the keyword regex, drops the touches inject', () => {
+    assert.ok(
+      /const needsMigration = autoDetect && detectsMigration\(body\.title, body\.description\)/.test(routesSrc),
+      'POST /tasks must derive needsMigration from detectsMigration(title, description)'
+    );
+    assert.ok(
+      /needsMigration,/.test(routesSrc),
+      'POST /tasks must pass needsMigration through to createTask'
+    );
+    assert.ok(
+      !/touches\.push\('migrations\/'\)/.test(routesSrc),
+      "POST /tasks must no longer push 'migrations/' into touches[]"
+    );
+  });
+
+  await test('capture.js no longer mirrors the migration regex', () => {
+    assert.ok(
+      !/MIGRATION_KEYWORD_RE/.test(captureSrc),
+      'the scripts/gds/capture.js keyword mirror must be deleted (server-side detection only)'
+    );
+  });
+
+  await test('allocation trigger: needs_migration is the only signal (the cutover)', () => {
+    assert.equal(shouldReserveMigrationNumber({ needs_migration: true, touches: [] }), true,
+      'boolean true → reserve, even with no touches');
+    assert.equal(shouldReserveMigrationNumber({ needs_migration: false, touches: [] }), false,
+      'boolean false → no reserve');
+    assert.equal(
+      shouldReserveMigrationNumber({ needs_migration: false, touches: ['migrations/', 'src/bongos/db.js'] }),
+      false,
+      "the old sentinel must NOT trigger allocation anymore — 'migrations/' in touches[] with the boolean false reserves nothing"
+    );
+  });
+
+  console.log(`\n${passed} passed, ${failed} failed`);
+  if (failed > 0) process.exit(1);
+})();