@bongos/core 1.21.106 → 1.21.107

package/modules/lifecycle/db-claims.js

@@ -37,6 +37,7 @@ const { claimGate, claimPermissionsFor, disambiguateWorktreeName, foldWorktreeNa
 const { sealSessionLog } = require('./db-shared.js');
 const { gatingRebaseTasksForBuilder, shouldRefuseClaimResolve } = require('./db-ship.js');
 const { REWARD_SUGGESTION_CAP, rewardGateAssignment } = require('./db-tasks.js');
+const { autoPickupRefusal } = require('./autopickup.js');
 
 // -------------------------------------------------------------------------
 // Claims (atomic)
@@ -99,8 +100,11 @@ function isRebaseGateExempt(task) {
   return Boolean(task) && task.kind === 'infra' && Number(task.priority) === 1;
 }
 
-async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSessionId, enforceOverlap = false }) {
+async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSessionId, enforceOverlap = false, autoPickup = false }) {
   const heldPermissions = await claimPermissionsFor(builderId); // BV1.R106 — before the tx opens
+  // ADR 0371 D5: a marked claim needs the project's switch and cap, read before the
+  // tx like the permissions above; the COUNT runs inside it, under the lock.
+  const autoPickupSettings = autoPickup ? await api.projectSettings.resolveTweakAutopickup() : null;
   const client = await pool.connect();
   try {
     await client.query('BEGIN');
@@ -142,7 +146,7 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     }
 
     const { rows: taskRows } = await client.query(
-      `SELECT id, status, touches, newcomer_friendly, requires_rank, needs_migration, module_key, credits_reward, reward_gate_exempt, est_minutes, kind, goal_id FROM tasks WHERE id = $1 FOR UPDATE`,
+      `SELECT id, status, touches, newcomer_friendly, requires_rank, needs_migration, module_key, credits_reward, reward_gate_exempt, est_minutes, kind, goal_id, source FROM tasks WHERE id = $1 FOR UPDATE`,
       [taskId]
     );
     if (taskRows.length === 0) {
@@ -350,6 +354,14 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
       }
     }
 
+    // ADR 0371 D5/D6 (task 1004677): the auto_pickup mark. The cap and the per-round
+    // limit are counted under a project-wide advisory lock that this transaction
+    // holds through the insert below, so two runners cannot both take the last slot.
+    if (autoPickup) {
+      const refusal = await autoPickupRefusal(client, task, autoPickupSettings);
+      if (refusal) throw refusal;
+    }
+
     // Pre-allocate a migration number if the task signals it'll add one.
     // Trigger: the tasks.needs_migration boolean (migration 081, touches[]
     // cleanup [1/8] / task 876). Replaced the old touches[]-contains-'migrations/'
@@ -396,9 +408,11 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
       finalWorktreeName = disambiguateWorktreeName(finalWorktreeName, taken);
     }
 
+    // The column is named only on a marked claim, so an ordinary claim's insert is
+    // byte-identical to before core_275.
     const insertClaim = await client.query(
-      `INSERT INTO claims (task_id, builder_id, worktree_name, requested_worktree_name, head_sha, reserved_migration_number, creator_session_id)
-       VALUES ($1, $2, $3, $4, $5, $6, $7)
+      `INSERT INTO claims (task_id, builder_id, worktree_name, requested_worktree_name, head_sha, reserved_migration_number, creator_session_id${autoPickup ? ', auto_pickup' : ''})
+       VALUES ($1, $2, $3, $4, $5, $6, $7${autoPickup ? ', TRUE' : ''})
        RETURNING id, task_id, builder_id, worktree_name, requested_worktree_name, claimed_at, head_sha, reserved_migration_number`,
       [taskId, builderId, finalWorktreeName, requestedWorktreeName, headSha ?? null, reservedMigrationNumber, creatorSessionId ?? null]
     );

package/modules/lifecycle/routes/claims.js

@@ -276,8 +276,12 @@ module.exports = function buildClaimsRouter() {
       // an interactive single-human claim only WARNS (git merge is the real
       // collision detector — ADR 0017).
       enforce_touches: { type: 'boolean' },
+      // ADR 0371 D5 (task 1004677): the Autobongos tweak lane's mark. The server
+      // counts marked claims against the project's monthly cap and the per-round
+      // limit; see modules/lifecycle/autopickup.js.
+      auto_pickup: { type: 'boolean' },
     })) return;
-    const { task_id: taskId, worktree_name: worktreeName, head_sha: headSha, bind_session: bindSession, enforce_touches: enforceTouches } = req.body || {};
+    const { task_id: taskId, worktree_name: worktreeName, head_sha: headSha, bind_session: bindSession, enforce_touches: enforceTouches, auto_pickup: autoPickup } = req.body || {};
     // Belt-and-braces — task_id must coerce to a finite number. Older calls
     // sent string ints (Number.isFinite passes both); reject NaN/garbage.
     if (!Number.isFinite(Number(taskId))) {
@@ -291,6 +295,7 @@ module.exports = function buildClaimsRouter() {
         headSha: headSha ?? null,
         creatorSessionId: resolveCreatorSessionId(bindSession, req.gdsSession?.session_id),
         enforceOverlap: enforceTouches === true,
+        autoPickup: autoPickup === true,
       });
       const { just_unlocked: justUnlocked, overlap_warning: overlapWarning, sibling_overlap_warning: siblingOverlapWarning, ...claim } = claimResult;
       const task = await db.getTask(Number(taskId));
@@ -375,6 +380,12 @@ module.exports = function buildClaimsRouter() {
           // block, not an authorization refusal). The refusal object already
           // carries `message` + `hint`, so no extra hint-building step needed.
           err.code === 'RELEVANCE_REVIEW_PENDING' ? 409 :
+          // ADR 0371 D5/D6: a marked auto-pickup claim the project's switch, monthly
+          // cap or per-round limit refuses. The round waits for a person.
+          err.code === 'AUTO_PICKUP_NOT_A_TWEAK' ? 409 :
+          err.code === 'AUTO_PICKUP_OFF' ? 409 :
+          err.code === 'AUTO_PICKUP_CAP_REACHED' ? 409 :
+          err.code === 'AUTO_PICKUP_ROUND_LIMIT' ? 409 :
           500;
         // V4.R14 (#952): a TASK_NOT_READY 409 names the way forward instead of
         // leaving the caller to discover the promote route by spelunking (#506).

package/modules/lifecycle/routes/project-settings.js

@@ -31,6 +31,7 @@
 const express = require('express');
 const api = require('../../../src/module-api');
 const goalCategory = require('../goal-category');
+const autopickup = require('../autopickup');
 
 const log = api.logger('lifecycle');
 
@@ -380,6 +381,64 @@ module.exports = function buildProjectSettingsRouter() {
     }
   });
 
+  // --- tweak auto-pickup (task 1004677, ADR 0371 D3/D5) ----------------------
+  //
+  // GET /project-settings/tweak-autopickup — the switch, the monthly cap, and how
+  // many rounds the lane has picked up this calendar month (counted from marked
+  // claims, never a stored counter).
+  //
+  // rank: any signed-in builder. The runner reads it before it tries a round, and
+  // the studio shows the count; it carries no reward internals or file paths.
+  async function autopickupBody() {
+    const resolved = await api.projectSettings.resolveTweakAutopickup();
+    const used = await autopickup.countThisMonth();
+    return {
+      mode: resolved.mode,
+      cap: resolved.cap,
+      used_this_month: used,
+      remaining_this_month: Math.max(0, resolved.cap - used),
+      per_round_limit: autopickup.MAX_AUTO_APPLIES_PER_ROUND,
+      source: resolved.source,
+      invalid: resolved.invalid,
+      sentence: api.projectSettings.describeTweakAutopickup(resolved),
+    };
+  }
+
+  router.get('/project-settings/tweak-autopickup', api.requireBuilder, async (req, res) => {
+    try {
+      res.set('Cache-Control', 'no-store');
+      res.json(await autopickupBody());
+    } catch (err) {
+      log.error(`GET /project-settings/tweak-autopickup: ${err && err.message}`);
+      res.fail('project_settings_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // PATCH /project-settings/tweak-autopickup — body { mode?: 'off' | 'on', cap?: n }.
+  //
+  // rank: project.settings.manage (metic+, government_010), the same atom as the
+  // other writes on this page. Each field is validated by the resolver's own parser,
+  // and both are checked before either is written, so a half-valid body writes nothing.
+  router.patch('/project-settings/tweak-autopickup', api.requireBuilder, api.requirePermission('project.settings.manage'), api.requireActAlone('rules'), async (req, res) => {
+    if (api.validateOrRespond(req, res, { mode: { type: 'string' }, cap: { type: 'number' } })) return;
+    const body = req.body || {};
+    if (body.mode == null && body.cap == null) {
+      return res.fail('bad_tweak_autopickup', { status: 400, message: 'send mode, cap, or both' });
+    }
+    const mode = body.mode == null ? null : api.projectSettings.parseAutopickup(body.mode);
+    if (mode && !mode.mode) return res.fail('bad_tweak_autopickup', { status: 400, message: `mode: ${mode.reason}` });
+    const cap = body.cap == null ? null : api.projectSettings.parseAutopickupCap(body.cap);
+    if (cap && cap.cap == null) return res.fail('bad_tweak_autopickup', { status: 400, message: `cap: ${cap.reason}` });
+    try {
+      if (mode) await api.projectSettings.set(api.projectSettings.KEYS.TWEAK_AUTOPICKUP, mode.mode, req.builder.id);
+      if (cap) await api.projectSettings.set(api.projectSettings.KEYS.TWEAK_AUTOPICKUP_CAP, cap.cap, req.builder.id);
+      res.json({ ok: true, ...(await autopickupBody()) });
+    } catch (err) {
+      log.error(`PATCH /project-settings/tweak-autopickup: ${err && err.message}`);
+      res.fail('project_settings_write_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   return router;
 };
 

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.106",
+  "version": "1.21.107",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.106",
+      "version": "1.21.107",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.106",
+  "version": "1.21.107",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -9482,5 +9482,11 @@
       "id": "1004683",
       "text": "After pressing Create, a founder now sees \"Getting <name> ready\" with a plain count (\"4 of 6 done\", or \"ready\" with a tick) and one sentence saying what is happening and whether it is their turn. Below it are two short lists,"
     }
+  ],
+  "1.21.107": [
+    {
+      "id": "1004677",
+      "text": "A project now has a switch for letting a runner pick up submitted page tweaks on its own, off by default, with a monthly limit of 20 rounds. The server enforces the limit when the work is claimed, so two runners can never both"
+    }
   ]
 }

package/scripts/gds/government-walk.js

@@ -70,6 +70,7 @@ const BAD = 'x';
 const REQUESTS = Object.freeze({
   'PATCH /project-settings/rot-days': ['PATCH', '/project-settings/rot-days', { days: 'soon' }],
   'PATCH /project-settings/ship-mode': ['PATCH', '/project-settings/ship-mode', { mode: 'sometimes' }],
+  'PATCH /project-settings/tweak-autopickup': ['PATCH', '/project-settings/tweak-autopickup', { mode: 'sometimes' }],
   'PATCH /work-categories/:id': ['PATCH', `/work-categories/${BAD}`, {}],
   'POST /security/reports/:id/confirm': ['POST', `/security/reports/${BAD}/confirm`, {}],
   'POST /security/reports/:id/dispute': ['POST', `/security/reports/${BAD}/dispute`, {}],

package/scripts/gds/run-unit-tests.js

@@ -121,6 +121,9 @@ const INTEGRATION = new Set([
   // index actually refuses the commingling INSERT and still allows the parallel
   // -worktree case. It self-skips without a DB, and refuses any database that
   // has a `builders` table, since it TRUNCATEs claims.
+  // task 1004677: two marked auto-pickup claims racing for the last slot of the
+  // monthly cap; only real connections prove the advisory lock. Scratch DB only.
+  'autopickup_cap_db',
   'claims_requested_worktree_db',
   'clawback_confirmed_backlog',
   // task 1003113: the copy_desk_flags schema half. The module's own tests are

package/src/bongos/project-settings.js

@@ -50,6 +50,8 @@ const SETTING_KEYS = {
   ROT_DAYS: 'attention.rot_days',
   FOCUS_VERSION: 'roadmap.focus_version',
   SHIP_MODE: 'ship.mode',
+  TWEAK_AUTOPICKUP: 'tweak.autopickup',
+  TWEAK_AUTOPICKUP_CAP: 'tweak.autopickup_monthly_cap',
 };
 
 // SHIP MODE (task 1004628, ADR 0369) — WHO starts a ship, never HOW it lands.
@@ -278,6 +280,75 @@ function describeShipMode(resolved) {
   return `${what}${how}`;
 }
 
+
+// TWEAK AUTO-PICKUP (task 1004677, ADR 0371 D3/D5). Whether the Autobongos runner's
+// tweak lane may pick up a submitted page round on its own, and how many rounds it
+// may pick up per calendar month. Off by default: a project that never turns it on
+// keeps today's queue exactly. The cap is ENFORCED by the server at claim time
+// (modules/lifecycle/autopickup.js); this file only resolves the numbers.
+const AUTOPICKUP_MODES = Object.freeze(['off', 'on']);
+const DEFAULT_AUTOPICKUP = 'off';
+// 20 rounds: a grade costs the project a few dollars, so 20 is a bounded, legible
+// monthly spend at about the level of one active artist (ADR 0371 D5).
+const DEFAULT_AUTOPICKUP_CAP = 20;
+// Past 1000 the cap is an off switch typed as a big number; that should be asked
+// for out loud, the same reasoning as MAX_ROT_DAYS.
+const MAX_AUTOPICKUP_CAP = 1000;
+
+function parseAutopickup(raw) {
+  if (raw == null || String(raw).trim() === '') return { reason: 'empty' };
+  const v = String(raw).trim().toLowerCase();
+  if (!AUTOPICKUP_MODES.includes(v)) return { reason: `must be one of ${AUTOPICKUP_MODES.join(' | ')}` };
+  return { mode: v };
+}
+
+function parseAutopickupCap(raw) {
+  if (raw == null || raw === '') return { reason: 'empty' };
+  const n = Number(raw);
+  if (!Number.isFinite(n)) return { reason: 'not a number' };
+  if (!Number.isInteger(n)) return { reason: 'must be a whole number of rounds' };
+  if (n <= 0) return { reason: 'must be positive' };
+  if (n > MAX_AUTOPICKUP_CAP) return { reason: `out of range (1..${MAX_AUTOPICKUP_CAP})` };
+  return { cap: n };
+}
+
+// One knob through its parser: { value, source, invalid }. Never throws; an
+// unreadable database answers the default, the resolveShipMode posture.
+async function resolveOne(key, parse, pick, fallback) {
+  let row = null;
+  try {
+    row = await getSetting(key);
+  } catch (err) {
+    logger.error(`project_settings read failed; falling back to the default ${key}: ${err && err.message}`);
+    return { value: fallback, source: 'default', invalid: null };
+  }
+  if (row && row.value != null && row.value !== '') {
+    const got = parse(row.value);
+    if (pick(got) != null) return { value: pick(got), source: 'project_settings', invalid: null };
+    return { value: fallback, source: 'default', invalid: { where: `project_settings['${key}']`, raw: String(row.value), reason: got.reason } };
+  }
+  return { value: fallback, source: 'default', invalid: null };
+}
+
+// resolveTweakAutopickup() — { mode, cap, source: { mode, cap }, invalid: [...] }.
+// mode is always 'off' or 'on', cap always a usable positive integer.
+async function resolveTweakAutopickup() {
+  const m = await resolveOne(SETTING_KEYS.TWEAK_AUTOPICKUP, parseAutopickup, (g) => g.mode, DEFAULT_AUTOPICKUP);
+  const c = await resolveOne(SETTING_KEYS.TWEAK_AUTOPICKUP_CAP, parseAutopickupCap, (g) => g.cap, DEFAULT_AUTOPICKUP_CAP);
+  return {
+    mode: m.value,
+    cap: c.value,
+    source: { mode: m.source, cap: c.source },
+    invalid: [m.invalid, c.invalid].filter(Boolean),
+  };
+}
+
+function describeTweakAutopickup(resolved) {
+  const r = resolved || {};
+  if (r.mode !== 'on') return 'Off: a submitted page waits until a person runs /tweak for it.';
+  return `On: a running Autobongos runner applies submitted pages on its own, up to ${r.cap} a month. The artist still approves every one.`;
+}
+
 // parseDays is exported for the tests only — the range check and the default are
 // asserted against the SAME constants the resolver reads, because a test that
 // re-typed 30 or 365 would be the second copy of the number this file exists to
@@ -299,4 +370,12 @@ module.exports = {
   parseShipMode,
   resolveShipMode,
   describeShipMode,
+  AUTOPICKUP_MODES,
+  DEFAULT_AUTOPICKUP,
+  DEFAULT_AUTOPICKUP_CAP,
+  MAX_AUTOPICKUP_CAP,
+  parseAutopickup,
+  parseAutopickupCap,
+  resolveTweakAutopickup,
+  describeTweakAutopickup,
 };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.106'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.107'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');
@@ -474,6 +474,13 @@ module.exports = {
     get parseShipMode() { return require('./bongos/project-settings').parseShipMode; },
     get resolveShipMode() { return require('./bongos/project-settings').resolveShipMode; },
     get describeShipMode() { return require('./bongos/project-settings').describeShipMode; },
+    // Tweak auto-pickup (task 1004677, ADR 0371 D3/D5): the switch and the monthly cap.
+    get AUTOPICKUP_MODES() { return require('./bongos/project-settings').AUTOPICKUP_MODES; },
+    get MAX_AUTOPICKUP_CAP() { return require('./bongos/project-settings').MAX_AUTOPICKUP_CAP; },
+    get parseAutopickup() { return require('./bongos/project-settings').parseAutopickup; },
+    get parseAutopickupCap() { return require('./bongos/project-settings').parseAutopickupCap; },
+    get resolveTweakAutopickup() { return require('./bongos/project-settings').resolveTweakAutopickup; },
+    get describeTweakAutopickup() { return require('./bongos/project-settings').describeTweakAutopickup; },
   },
   readConfigFileSync: instanceConfig.readConfigFileSync,
   configHome: instanceConfig.configHome,

package/tests/autopickup_cap.mjs

@@ -0,0 +1,236 @@
+// tests/autopickup_cap.mjs — tweak auto-pickup's setting, monthly cap and claim mark
+// (task 1004677 / BV2.TW19a, ADR 0371 D3, D5, D6).
+//
+// Pinned here (DB-free; the race lives in tests/autopickup_cap_db.mjs):
+//   1. the two parsers and the resolver: off by default, cap 20 by default, an
+//      unusable stored value reported and never thrown, a dead DB answers defaults;
+//   2. the refusal ladder: not a tweak, switch off, round limit, monthly cap, and the
+//      lock is taken BEFORE either count;
+//   3. claimTask: a marked claim runs the gate before the insert and names the
+//      column; an unmarked claim's insert is unchanged;
+//   4. the routes: any builder reads (with this month's count), only
+//      project.settings.manage writes, and a half-valid body writes nothing.
+//
+// Run:  node --test tests/autopickup_cap.mjs
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const poolMod = require(path.join(ROOT, 'src', 'bongos', 'pool.js'));
+const {
+  DEFAULT_AUTOPICKUP, DEFAULT_AUTOPICKUP_CAP, parseAutopickup, parseAutopickupCap,
+  resolveTweakAutopickup, describeTweakAutopickup, SETTING_KEYS, AUTOPICKUP_MODES, MAX_AUTOPICKUP_CAP,
+} = require('../src/bongos/project-settings.js');
+const { autoPickupRefusal, LOCK_KEY, MAX_AUTO_APPLIES_PER_ROUND } = require('../modules/lifecycle/autopickup.js');
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+
+async function withPool(query, fn) {
+  const pool = poolMod.pool;
+  const saved = pool.query;
+  pool.query = query;
+  try { return await fn(); } finally { pool.query = saved; }
+}
+const settingsRows = (map) => async (_sql, [key]) => ({ rows: key in map ? [{ key, value: map[key] }] : [] });
+
+// ---- 1. the setting ---------------------------------------------------------
+
+test('the parsers accept exactly off|on and a whole positive cap', () => {
+  assert.deepEqual([...AUTOPICKUP_MODES], ['off', 'on']);
+  assert.equal(api.projectSettings.MAX_AUTOPICKUP_CAP, MAX_AUTOPICKUP_CAP, 'the doorway hands out the same bound');
+  assert.deepEqual(parseAutopickup(' On '), { mode: 'on' });
+  assert.match(parseAutopickup('maybe').reason, /off \| on/);
+  assert.deepEqual(parseAutopickupCap('5'), { cap: 5 });
+  assert.match(parseAutopickupCap('0').reason, /positive/);
+  assert.match(parseAutopickupCap('2.5').reason, /whole/);
+  assert.match(parseAutopickupCap('100000').reason, /out of range/);
+});
+
+test('an untouched project is off with a cap of 20', async () => {
+  assert.equal(DEFAULT_AUTOPICKUP, 'off');
+  assert.equal(DEFAULT_AUTOPICKUP_CAP, 20);
+  const r = await withPool(settingsRows({}), () => resolveTweakAutopickup());
+  assert.deepEqual(r, { mode: 'off', cap: 20, source: { mode: 'default', cap: 'default' }, invalid: [] });
+  assert.match(describeTweakAutopickup(r), /waits until a person/);
+});
+
+test('stored values are read; an unusable one is reported and falls back', async () => {
+  const r = await withPool(settingsRows({ [SETTING_KEYS.TWEAK_AUTOPICKUP]: 'on', [SETTING_KEYS.TWEAK_AUTOPICKUP_CAP]: 'lots' }),
+    () => resolveTweakAutopickup());
+  assert.equal(r.mode, 'on');
+  assert.equal(r.source.mode, 'project_settings');
+  assert.equal(r.cap, 20);
+  assert.equal(r.invalid.length, 1);
+  assert.equal(r.invalid[0].raw, 'lots');
+  assert.match(describeTweakAutopickup({ mode: 'on', cap: 7 }), /up to 7 a month/);
+});
+
+test('a database that cannot be read answers the defaults', async () => {
+  const r = await withPool(async () => { throw new Error('db down'); }, () => resolveTweakAutopickup());
+  assert.equal(r.mode, 'off');
+  assert.equal(r.cap, 20);
+});
+
+// ---- 2. the refusal ladder --------------------------------------------------
+
+function fakeClient({ round = 0, month = 0 } = {}) {
+  const calls = [];
+  return {
+    calls,
+    async query(sql, params) {
+      calls.push(sql.includes('pg_advisory_xact_lock') ? `lock:${params[0]}` : sql.includes('date_trunc') ? 'month' : 'round');
+      if (sql.includes('pg_advisory_xact_lock')) return { rows: [] };
+      return { rows: [{ n: sql.includes('date_trunc') ? month : round }] };
+    },
+  };
+}
+const tweak = { id: 9, source: 'page-tweak' };
+const on = { mode: 'on', cap: 3 };
+
+test('a marked claim on anything but a page tweak is refused, before any lock', async () => {
+  const c = fakeClient();
+  assert.equal((await autoPickupRefusal(c, { id: 9, source: 'manual' }, on)).code, 'AUTO_PICKUP_NOT_A_TWEAK');
+  assert.deepEqual(c.calls, []);
+});
+
+test('the switch off refuses a marked claim', async () => {
+  assert.equal((await autoPickupRefusal(fakeClient(), tweak, { mode: 'off', cap: 3 })).code, 'AUTO_PICKUP_OFF');
+});
+
+test('the lock is taken before either count, on the one project-wide key', async () => {
+  const c = fakeClient();
+  assert.equal(await autoPickupRefusal(c, tweak, on), null);
+  assert.equal(LOCK_KEY, 'page-tweak/autopickup');
+  assert.deepEqual(c.calls, ['lock:page-tweak/autopickup', 'round', 'month']);
+});
+
+test('a third automatic apply of one round is refused', async () => {
+  assert.equal(MAX_AUTO_APPLIES_PER_ROUND, 2);
+  assert.equal(await autoPickupRefusal(fakeClient({ round: 1 }), tweak, on), null);
+  const r = await autoPickupRefusal(fakeClient({ round: 2 }), tweak, on);
+  assert.equal(r.code, 'AUTO_PICKUP_ROUND_LIMIT');
+  assert.match(r.message, /waits for a person/);
+});
+
+test('the monthly cap refuses at the cap and admits below it', async () => {
+  assert.equal(await autoPickupRefusal(fakeClient({ month: 2 }), tweak, on), null);
+  const r = await autoPickupRefusal(fakeClient({ month: 3 }), tweak, on);
+  assert.equal(r.code, 'AUTO_PICKUP_CAP_REACHED');
+  assert.equal(r.cap, 3);
+});
+
+// ---- 3. claimTask wiring ----------------------------------------------------
+
+test('claimTask runs the gate before the insert, and names the column only on a marked claim', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'lifecycle', 'db-claims.js'), 'utf8');
+  const body = src.slice(src.indexOf('async function claimTask('), src.indexOf('async function claimTasksBatch'));
+  const gate = body.indexOf('autoPickupRefusal(client, task, autoPickupSettings)');
+  const insert = body.indexOf('INSERT INTO claims');
+  assert.ok(gate > 0 && insert > gate, 'the gate runs inside the transaction, before the insert');
+  assert.match(body.slice(gate, insert), /if \(refusal\) throw refusal;/, 'a refusal stops the claim');
+  assert.match(body, /\$\{autoPickup \? ', auto_pickup' : ''\}/);
+  assert.match(body, /goal_id, source FROM tasks WHERE id = \$1 FOR UPDATE/, 'the task row carries its source');
+});
+
+test('POST /claims accepts auto_pickup and maps every refusal to a 409', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'modules', 'lifecycle', 'routes', 'claims.js'), 'utf8');
+  assert.match(src, /auto_pickup: \{ type: 'boolean' \}/);
+  assert.match(src, /autoPickup: autoPickup === true/);
+  for (const code of ['AUTO_PICKUP_NOT_A_TWEAK', 'AUTO_PICKUP_OFF', 'AUTO_PICKUP_CAP_REACHED', 'AUTO_PICKUP_ROUND_LIMIT']) {
+    assert.match(src, new RegExp(`err.code === '${code}' \\? 409`));
+  }
+});
+
+// ---- 4. the routes ----------------------------------------------------------
+
+const fakeRes = () => ({
+  code: null, statusCode: 200, payload: null, headers: {},
+  fail(code, opts) { this.code = code; this.statusCode = opts?.status ?? 400; this.payload = { error: code, ...(opts || {}) }; return this; },
+  status(c) { this.statusCode = c; return this; },
+  set(k, v) { this.headers[k] = v; return this; },
+  json(p) { this.payload = p; return this; },
+});
+
+function buildRouter({ used = 4 } = {}) {
+  const ps = api.projectSettings;
+  const saved = { resolve: ps.resolveTweakAutopickup, set: ps.set };
+  const writes = [];
+  const state = { mode: 'off', cap: 20 };
+  ps.resolveTweakAutopickup = async () => ({ ...state, source: { mode: 'default', cap: 'default' }, invalid: [] });
+  ps.set = async (key, value, by) => {
+    writes.push({ key, value, by });
+    if (key === 'tweak.autopickup') state.mode = value; else state.cap = value;
+  };
+  const autopickup = require('../modules/lifecycle/autopickup.js');
+  const savedCount = autopickup.countThisMonth;
+  autopickup.countThisMonth = async () => used;
+  const file = path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js');
+  delete require.cache[require.resolve(file)];
+  const router = require(file)();
+  const route = (method, p) => router.stack.find((l) => l.route && l.route.path === p && l.route.methods[method]).route;
+  const restore = () => { ps.resolveTweakAutopickup = saved.resolve; ps.set = saved.set; autopickup.countThisMonth = savedCount; };
+  return { route, writes, restore };
+}
+const handler = (r) => r.stack[r.stack.length - 1].handle;
+
+test('the read is open to any builder and reports this month\'s count against the cap', async () => {
+  const { route, restore } = buildRouter({ used: 4 });
+  try {
+    const get = route('get', '/project-settings/tweak-autopickup');
+    assert.equal(get.stack.length, 2, 'requireBuilder + the handler');
+    const res = fakeRes();
+    await handler(get)({}, res);
+    assert.equal(res.payload.mode, 'off');
+    assert.equal(res.payload.used_this_month, 4);
+    assert.equal(res.payload.remaining_this_month, 16);
+    assert.equal(res.payload.per_round_limit, 2);
+    assert.equal(res.headers['Cache-Control'], 'no-store');
+  } finally { restore(); }
+});
+
+test('the write is gated on project.settings.manage and the Rules decision rule', () => {
+  const { route, restore } = buildRouter();
+  try {
+    const write = route('patch', '/project-settings/tweak-autopickup').stack;
+    assert.equal(write.length, 4);
+    assert.equal(write[2].handle.name, 'actAloneGate');
+    const src = fs.readFileSync(path.join(ROOT, 'modules', 'lifecycle', 'routes', 'project-settings.js'), 'utf8');
+    assert.match(src, /router\.patch\('\/project-settings\/tweak-autopickup', api\.requireBuilder, api\.requirePermission\('project\.settings\.manage'\)/);
+  } finally { restore(); }
+});
+
+test('a half-valid body writes nothing; a good one writes both and echoes the new read', async () => {
+  const { route, writes, restore } = buildRouter({ used: 0 });
+  try {
+    const patch = handler(route('patch', '/project-settings/tweak-autopickup'));
+    const bad = fakeRes();
+    await patch({ body: { mode: 'on', cap: 0 }, builder: { id: 7 } }, bad);
+    assert.equal(bad.code, 'bad_tweak_autopickup');
+    assert.equal(writes.length, 0);
+
+    const empty = fakeRes();
+    await patch({ body: {}, builder: { id: 7 } }, empty);
+    assert.equal(empty.code, 'bad_tweak_autopickup');
+
+    const good = fakeRes();
+    await patch({ body: { mode: 'ON', cap: 5 }, builder: { id: 7 } }, good);
+    assert.equal(good.code, null);
+    assert.deepEqual(writes, [
+      { key: 'tweak.autopickup', value: 'on', by: 7 },
+      { key: 'tweak.autopickup_monthly_cap', value: 5, by: 7 },
+    ]);
+    assert.equal(good.payload.mode, 'on');
+    assert.equal(good.payload.cap, 5);
+  } finally { restore(); }
+});
+
+test('core_275 is additive: one nullable column, recorded in schema_migrations', () => {
+  const sql = fs.readFileSync(path.join(ROOT, 'migrations', 'core_275_claims_auto_pickup.sql'), 'utf8');
+  assert.match(sql, /ALTER TABLE claims ADD COLUMN IF NOT EXISTS auto_pickup boolean;/);
+  assert.doesNotMatch(sql, /NOT NULL|DROP /);
+  assert.match(sql, /INSERT INTO schema_migrations \(version\) VALUES \('core_275_claims_auto_pickup'\)/);
+});