@bongos/core 1.19.316 → 1.19.318

package/modules/lifecycle/db-claims.js

@@ -0,0 +1,934 @@
+// modules/lifecycle/db-claims.js — the claim refusal ladder — claimTask, batch claim/release + batch validation.
+//
+// Carved out of modules/lifecycle/db.js by task 1003204 (goal 1000079, the R03
+// de-monolith plan) — a STRUCTURAL move, not a rewrite: the code below is the
+// original db.js lines 2540-3441 unchanged. db.js remains the facade that
+// re-exports every name, so every existing db call site is unchanged.
+//
+// THE BOUNDARY (ADR 0093 §1): this file reaches core ONLY through the published
+// doorway ../../src/module-api.js — never a core internal, never a sibling module.
+
+'use strict';
+
+const api = require('../../src/module-api');
+const { pool, withTx } = api;
+const log = api.logger('lifecycle');
+const seams = api;
+const { touchesOverlap } = api.pathMatch;
+const { claimEligibilityAllows, CLAIM_ANY, CLAIM_NEWCOMER } = require('./claim-eligibility.js');
+const { goalMembershipFailures } = require('./claim-feed.js');
+const { unsatisfiedDeps } = require('./db-deps-criteria.js');
+const { claimPermissionsFor, disambiguateWorktreeName, foldWorktreeName, rankAllowsTask, xenosClaimAllowed } = require('./db-rank-authz.js');
+const { sealSessionLog } = require('./db-shared.js');
+const { needsRebaseTasksForBuilder } = require('./db-ship.js');
+const { REWARD_SUGGESTION_CAP, rewardGateAssignment } = require('./db-tasks.js');
+
+// -------------------------------------------------------------------------
+// Claims (atomic)
+// -------------------------------------------------------------------------
+
+// Tries to atomically claim a task. Returns the claim row on success.
+// Throws { code: 'ALREADY_CLAIMED' } if another builder beat us to it.
+// Throws { code: 'TASK_NOT_READY' } if the task isn't in 'ready'.
+// Throws { code: 'TOUCHES_CONFLICT' } if a different active claim has
+// overlapping touches[] (caught BEFORE the unique-violation, so we
+// give a useful error rather than a generic constraint failure).
+
+// task 1002589 (idea 1000638) — a claims INSERT can trip TWO partial unique
+// indexes, and each means something different to the caller:
+//   uniq_active_claim_per_task — race lost: another session claimed the task.
+//   the per-session backstop — this session already holds a bound active claim
+//     in the same working tree. Collapsing this case onto ALREADY_CLAIMED sent
+//     builders hunting a phantom rival claimant while the target task sat
+//     'ready'.
+// Both generations of the backstop index map to the honest code: a deploy
+// applies code and migration at different instants, and an instance may still
+// carry the old index.
+const SESSION_CLAIM_INDEXES = new Set([
+  'uniq_active_claim_per_session',           // migration 180 — session-only (pre-re-key)
+  'uniq_active_claim_per_session_worktree',  // core_204 (task 1002570) — per (session, stored worktree)
+  // core_221 (task 1002709) — per (session, REQUESTED worktree). All three
+  // generations stay listed: a deploy applies code and migration at different
+  // instants, so an instance may still carry an older index, and an unrecognised
+  // constraint falls closed onto the generic ALREADY_CLAIMED — which for this
+  // case is the wrong, phantom-rival answer.
+  'uniq_active_claim_per_session_requested_worktree',
+]);
+// Branch on err.constraint; an UNKNOWN constraint fails CLOSED on the generic
+// ALREADY_CLAIMED (never widen a claim refusal). Pure + exported for DB-free
+// tests; claimTask enriches the session case with the in-flight claim's id.
+function claimUniqueViolationError(err) {
+  if (err && SESSION_CLAIM_INDEXES.has(err.constraint)) {
+    return {
+      code: 'session_already_has_bound_claim',
+      what_to_do: 'Ship or release the in-flight claim first (/builder-ship or /builder-release), '
+        + 'or claim this task from its own separate worktree (since core_204 the index allows '
+        + 'one bound claim per worktree). {"bind_session":false} (an unbound claim) always coexists.',
+    };
+  }
+  return { code: 'ALREADY_CLAIMED' };
+}
+
+async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSessionId, enforceOverlap = false }) {
+  const heldPermissions = await claimPermissionsFor(builderId); // BV1.R106 — before the tx opens
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // V3.R88 (#307): a deactivated builder cannot claim new work. Their
+    // history is preserved, but they're out of the active rotation until an
+    // Archon reactivates them.
+    const { rows: builderRows } = await client.query(
+      `SELECT status, rank FROM builders WHERE id = $1`,
+      [builderId]
+    );
+    if (builderRows[0] && builderRows[0].status === 'inactive') {
+      throw { code: 'BUILDER_INACTIVE' };
+    }
+    const builderRank = builderRows[0] ? builderRows[0].rank : null;
+
+    // ADR 0120 part 3: the needs_rebase claim gate. A builder who owes a rebase
+    // on any un-landed confirmed task (flagged by the reconciler, part 2) is
+    // blocked from taking on NEW work until they LAND it (rebase the branch +
+    // re-ship → reconciler) or RELEASE it — both clear the flag. Their
+    // already-active claims are untouched (we only refuse fresh claims, never
+    // freeze in-flight work). Since the reward now lands only on ship (part 1),
+    // the builder is motivated to clear it; since it gates their queue, they
+    // can't walk away from it. Runs in THIS txn so it can't race a concurrent
+    // ship that clears the last flag.
+    const owedRebases = await needsRebaseTasksForBuilder(builderId, client);
+    if (owedRebases.length > 0) {
+      throw {
+        code: 'REBASE_REQUIRED',
+        rebaseTasks: owedRebases.map((t) => ({ id: t.id, title: t.title, reason: t.needs_rebase_reason })),
+      };
+    }
+
+    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`,
+      [taskId]
+    );
+    if (taskRows.length === 0) {
+      throw { code: 'TASK_NOT_FOUND' };
+    }
+    const task = taskRows[0];
+    if (task.status !== 'ready') {
+      throw { code: 'TASK_NOT_READY', currentStatus: task.status };
+    }
+
+    // task 1002650 (idea 1000644): the claimable FEED filters out ready tasks
+    // with an open blocker link, but the direct claim-by-id path never checked —
+    // the feed hid the trap and this path walked into it. Mirror migration 176's
+    // task_is_fully_unblocked clause so both gates enforce the same rule.
+    const { rows: openBlockers } = await client.query(
+      `SELECT b.id, b.title
+         FROM task_blockers tb
+         JOIN blockers b ON b.id = tb.blocker_id
+        WHERE tb.task_id = $1
+          AND b.status = 'open'
+        ORDER BY b.id`,
+      [taskId]
+    );
+    if (openBlockers.length > 0) {
+      throw { code: 'OPEN_BLOCKER', blockers: openBlockers };
+    }
+
+    // Three-rank model (task #360 / ADR 0018; V3.R15 #239): a Xenos is the
+    // sandboxed entry rank and may claim ONLY tasks explicitly opened to them
+    // (newcomer_friendly). Metic+ (the approved working rank) and Archon claim
+    // any ready task. This is the server-enforced half of C2's "Xenos ships
+    // only explicitly-tagged-open tasks" — markdown describes it, this check
+    // enforces it. Error code is rank_too_low_for_task (V3.R15); XENOS_RESTRICTED
+    // is kept as an alias on the error object for callers on the pre-rename
+    // release. BV1.R106 (ADR 0151): same rule, now decided on the PERMISSIONS
+    // task.claim.any / task.claim.newcomer — see ./claim-eligibility.js.
+    const newcomerFriendly = task.newcomer_friendly;
+    if (!claimEligibilityAllows({ heldPermissions, newcomerFriendly, rankRuleAllows: xenosClaimAllowed(builderRank, newcomerFriendly) })) {
+      // task 1002613 (map §4.4): the bare code reported a PERMISSION decision as
+      // a rank one — no axis, no remedy. Copy INSUFFICIENT_RANK's shape below:
+      // name both sides of the wall and the way forward.
+      const opened = newcomerFriendly === true;
+      throw {
+        code: 'rank_too_low_for_task',
+        legacy_code: 'XENOS_RESTRICTED',
+        required: opened ? [CLAIM_ANY, CLAIM_NEWCOMER] : [CLAIM_ANY],
+        actual: builderRank,
+        newcomer_friendly: opened,
+        message: opened
+          ? `claiming this task needs ${CLAIM_ANY} or ${CLAIM_NEWCOMER}, and your role holds neither`
+          : `this task is not opened to newcomers (newcomer_friendly is not set) and your role lacks ${CLAIM_ANY}`,
+        hint: opened
+          ? 'your builder appears to hold no claim permission at all — ask for your rank-role to be re-synced'
+          : 'pick a newcomer_friendly task from the claimable feed (/builder-start), or a builder whose role holds task.claim.any can claim this one',
+      };
+    }
+
+    // V3.R82 (#301): the inverse gate — a task can RAISE its minimum required
+    // rank above the default. requires_rank='metic' blocks Xenos; 'archon'
+    // blocks Xenos+Metic. The DB CHECK on tasks.requires_rank enforces the
+    // enum, so we trust the value here. INSUFFICIENT_RANK carries the actual
+    // and required ranks so the caller can render a clean error.
+    if (!rankAllowsTask(builderRank, task.requires_rank)) {
+      throw {
+        code: 'INSUFFICIENT_RANK',
+        required: task.requires_rank,
+        actual: builderRank,
+      };
+    }
+
+    // task 1003137 (owner ruling 2026-08-19): a task's goal requires MEMBERSHIP —
+    // every goal, catch-alls included; goal_id NULL is NOT gated. After the rank
+    // gates (membership only narrows — it must never mask a rank refusal),
+    // before deps. Decision + leak rule: goal-authz.goalMembershipClaimRefusal;
+    // the SAME extracted check runs in claimTasksBatch (the only other INSERT
+    // INTO claims site) — see claim-feed.js.
+    const goalRefusals = await goalMembershipFailures({ client, tasks: [task], builderId, builderRank });
+    if (goalRefusals.length > 0) throw goalRefusals[0].refusal;
+
+    // The claim gate (ADR 0015, generalized in task 1516 / ADR 0086 §5): a task
+    // can't be claimed while any dependency is un-done — its OWN edges plus those
+    // inherited from its goal/criteria, where "done" = task shipped | criterion
+    // satisfied | goal achieved. The auto-promotion triggers keep backlog tasks
+    // gated, but a manually-promoted task could end up 'ready' with pending deps —
+    // this is the second line of defence. Wire code stays DEPS_NOT_SHIPPED.
+    const unmetDeps = await unsatisfiedDeps(taskId, client);
+    if (unmetDeps.length > 0) {
+      throw {
+        code: 'DEPS_NOT_SHIPPED',
+        deps: unmetDeps.map((r) => ({ kind: r.kind, id: r.id, title: r.title, status: r.state })),
+      };
+    }
+
+    // task 1670 / ADR 0096 + task 1673 amendment: the reward backstop now
+    // AUTO-ASSIGNS instead of blocking. No task ships paying 0 drachmae — but a
+    // claim is never REFUSED for it. If credits_reward is 0/NULL at claim time
+    // (a backlog task that auto-promoted before 178, a manually-flipped 'ready'
+    // row, a reward zeroed after promotion, or one of the ~27 grandfathered
+    // reward_gate_exempt tasks), assign the capped suggestion HERE — inside this
+    // same FOR UPDATE transaction, so the value is set and the claim commit
+    // together atomically. AUDIT: a log line + the visible credits_reward change.
+    const rewardAssign = rewardGateAssignment(task);
+    if (rewardAssign) {
+      await client.query(
+        `UPDATE tasks SET credits_reward = $1, updated_at = now() WHERE id = $2`,
+        [rewardAssign.assign, taskId]
+      );
+      task.credits_reward = rewardAssign.assign;
+      console.log(`[reward-gate] AUTO-ASSIGN task ${taskId} credits_reward -> ${rewardAssign.assign} (cap ${REWARD_SUGGESTION_CAP}) [claim by builder ${builderId}]`);
+    }
+
+    let overlapWarning = null;
+    // touches[] cleanup [5/8] (task 880): prefix-aware overlap vs every OTHER
+    // active claim, computed in JS with the canonical matcher. The old SQL `&&`
+    // only caught exact-element overlap, so ['src/bongos/'] and ['src/bongos/db.js']
+    // slipped past it. Active claims are bounded by the number of concurrent
+    // builders, so fetching their touches and comparing in JS is cheap.
+    //
+    // The result is ADVISORY by default (ADR 0017: a hard 409 turned correct,
+    // mergeable work into deferred backlog — git merge is the real collision
+    // detector). It becomes a HARD precondition only when enforceOverlap=true,
+    // which the autonomous --parallel runner sets: there, two same-footprint
+    // tasks fanned into concurrent unsupervised agents could semantically
+    // clobber each other in ways git won't flag (parallel_safe covers non-file
+    // hazards, not file adjacency).
+    const { rows: activeClaimRows } = await client.query(
+      `SELECT c.id, t.id AS task_id, t.title, t.touches, t.module_key FROM claims c
+         JOIN tasks t ON t.id = c.task_id
+        WHERE c.released_at IS NULL AND t.id <> $1`,
+      [taskId]
+    );
+    // BV1.R53 (task 1422): module-disjointness is a HARD gate (not advisory) when
+    // both tasks carry a module_key. Two tasks in the same module are always a
+    // semantic conflict — their work inherently overlaps regardless of which files
+    // they predict. Two tasks in DIFFERENT modules are always safe (file-path
+    // overlap between modules is a fitness-function violation, not a runtime
+    // concern). module_key disjointness supersedes the touches[] check for
+    // module-keyed tasks and is never advisory.
+    if (task.module_key) {
+      const sameModuleConflicts = activeClaimRows.filter((r) => r.module_key === task.module_key);
+      if (sameModuleConflicts.length > 0) {
+        throw {
+          code: 'MODULE_CONFLICT',
+          module_key: task.module_key,
+          conflictTaskTitles: sameModuleConflicts.map((r) => r.title),
+        };
+      }
+    }
+    // touches[] overlap check applies only when module_key is absent on either side.
+    const overlapping = activeClaimRows.filter(
+      (r) => !(task.module_key && r.module_key) && touchesOverlap(task.touches, r.touches)
+    );
+    if (overlapping.length > 0) {
+      const titles = overlapping.map((r) => r.title);
+      if (enforceOverlap) {
+        throw { code: 'TOUCHES_CONFLICT', conflictTaskTitles: titles };
+      }
+      overlapWarning = titles;
+    }
+
+    // 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/'
+    // string sentinel so allocation no longer rides on a drifting path array.
+    let reservedMigrationNumber = null;
+    if (task.needs_migration === true) {
+      const { rows: bumpRows } = await client.query(
+        `UPDATE migration_counter
+            SET next_number = next_number + 1
+          WHERE id = 1
+          RETURNING next_number - 1 AS allocated`
+      );
+      reservedMigrationNumber = bumpRows[0].allocated;
+    }
+
+    // V3.R51 (#270): server-side worktree_name uniqueness across ACTIVE claims.
+    // `released_at IS NULL` is exactly the active set (same predicate as the
+    // touches-conflict check above and uniq_active_claim_per_task). A name freed
+    // by a resolved claim won't appear here, so it's reused without a suffix —
+    // which is what the overnight builder relies on. We hold FOR UPDATE on the
+    // task row already; reading the active names inside the same txn is good
+    // enough for the disambiguation to be stable for this insert.
+    // task 1002522: fold ''/whitespace → NULL before anything keys on the name.
+    // core_204's index folds them together anyway (COALESCE(worktree_name, ''));
+    // normalizing here means the stored row matches what the guard compared.
+    // task 1002709: BOTH names are stored, and they answer different questions.
+    // `requestedWorktreeName` is what the caller asked for — the identity of the
+    // working TREE, which is what "do these two claims share a tree" actually
+    // asks. `finalWorktreeName` is what lands on disk after disambiguation, which
+    // is what must stay globally unique across active claims.
+    //
+    // Keying the one-claim-per-tree guard on the STORED name was the hole: a
+    // second claim from the same session in the same tree compared "overnight"
+    // against a previously-renamed "overnight-2", saw a different tree, and let
+    // a commingling claim through. See core_221 for the full repro.
+    const requestedWorktreeName = foldWorktreeName(worktreeName);
+    let finalWorktreeName = requestedWorktreeName;
+    if (finalWorktreeName) {
+      const { rows: activeNameRows } = await client.query(
+        `SELECT worktree_name FROM claims
+          WHERE released_at IS NULL AND worktree_name IS NOT NULL`
+      );
+      const taken = new Set(activeNameRows.map((r) => r.worktree_name));
+      finalWorktreeName = disambiguateWorktreeName(finalWorktreeName, taken);
+    }
+
+    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)
+       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]
+    );
+
+    await client.query(`UPDATE tasks SET status = 'active' WHERE id = $1`, [taskId]);
+
+    // Gamification carved to modules/economy/ (BV1.R77 / ADR 0093 §1-2): resolve
+    // the `reward` kernel port and fire the claim hook inside this same txn.
+    const justUnlocked = await seams.resolveOptional('reward').evaluateAfterClaim(
+      client, builderId, insertClaim.rows[0].id
+    );
+
+    // V3.R75 (#294): tick the onboarding state machine for first_claim. Done
+    // inside the same transaction so the claim and onboarding write commit
+    // together. Wrapped in try/catch so an onboarding-table issue can't
+    // block a legitimate claim. The onboarding state machine carved into
+    // modules/onboarding/ (BV1.R81 / ADR 0093 §1): resolve the `onboarding`
+    // kernel port and pass this txn `client` — never a direct require of a
+    // module. Default-on, so present in prod; the ?. degrades to a no-op (the
+    // state tick is best-effort anyway) when the module is off.
+    let graduationBuilder = null;
+    try {
+      const onboarding = seams.resolveOptional('onboarding');
+      const result = onboarding && await onboarding.markStage(client, builderId, 'first_claim');
+      if (result && result.justGraduated) {
+        const { rows: br } = await client.query(
+          `SELECT id, display_name, github_login FROM builders WHERE id = $1`,
+          [builderId]
+        );
+        graduationBuilder = br[0] || null;
+      }
+    } catch (e) {
+      console.log('[gds] claimTask onboarding markStage failed (non-blocking):', e && e.message);
+    }
+
+    await client.query('COMMIT');
+    if (graduationBuilder) {
+      try {
+        seams.resolveOptional('onboarding')?.broadcastGraduation(graduationBuilder);
+      } catch (e) {
+        console.log('[gds] graduation broadcast post-claim failed:', e && e.message);
+      }
+    }
+    return { ...insertClaim.rows[0], just_unlocked: justUnlocked, overlap_warning: overlapWarning };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    if (err && err.code === '23505') {
+      // task 1002589: branch on WHICH unique index tripped — see
+      // claimUniqueViolationError above. The session case is enriched with the
+      // in-flight bound claim (post-ROLLBACK, same client) so the refusal
+      // points at the real cause; best-effort — the honest code must not
+      // depend on this read succeeding.
+      let mapped = claimUniqueViolationError(err);
+      if (mapped.code === 'session_already_has_bound_claim' && creatorSessionId) {
+        try {
+          // Same-worktree row first: under the core_204 index that is the
+          // exact colliding claim; under the old session-only index any bound
+          // row of the session is the culprit, so fall back to the earliest.
+          const { rows } = await client.query(
+            `SELECT c.task_id, t.title
+               FROM claims c JOIN tasks t ON t.id = c.task_id
+              WHERE c.creator_session_id = $1 AND c.released_at IS NULL
+              ORDER BY (COALESCE(c.worktree_name, '') = COALESCE($2, '')) DESC, c.claimed_at, c.id
+              LIMIT 1`,
+            [creatorSessionId, worktreeName ?? null]
+          );
+          if (rows[0]) {
+            mapped = { ...mapped, active_task_id: Number(rows[0].task_id), active_task_title: rows[0].title };
+          }
+        } catch (_) { /* enrichment only — the mapped code still throws */ }
+      }
+      throw mapped;
+    }
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// Atomically claim N tasks in a single transaction. All-or-nothing.
+//
+// Mirrors claimTask's semantics for each task in the batch but runs inside ONE
+// BEGIN/COMMIT, so a partial failure (any one task being unready / already
+// claimed / touches-conflicting) rolls back the whole batch. The caller is
+// never left holding a half-acquired set.
+//
+// Additional check beyond the single-claim path: inter-batch touches conflict.
+// Within the requested set, no two tasks may have overlapping touches[]. The
+// optimizer should already filter these on the way in, but the server
+// re-validates so a stale client can't sneak through.
+//
+// On failure, throws { code: 'BATCH_FAILED', failures: [{ task_id, reason }] }.
+// Reasons mirror the single-claim error codes (TASK_NOT_FOUND, TASK_NOT_READY,
+// TOUCHES_CONFLICT, ALREADY_CLAIMED) plus 'BATCH_TOUCHES_CONFLICT' for
+// intra-batch overlap.
+
+async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSessionId }) {
+  if (!Array.isArray(taskIds) || taskIds.length === 0) {
+    throw { code: 'BATCH_EMPTY' };
+  }
+  const uniqIds = Array.from(new Set(taskIds.map(Number)));
+  if (uniqIds.length !== taskIds.length) {
+    throw { code: 'BATCH_DUPLICATE_IDS' };
+  }
+  // Stable-sort the IDs before SELECT FOR UPDATE so two concurrent batches
+  // sharing any rows can't deadlock by locking in opposite orders.
+  uniqIds.sort((a, b) => a - b);
+
+  // BV1.R106: resolved BEFORE the tx opens — see claimPermissionsFor.
+  const heldPermissions = await claimPermissionsFor(builderId);
+  const client = await pool.connect();
+  try {
+    await client.query('BEGIN');
+
+    // V3.R88 (#307): a deactivated builder can't batch-claim either.
+    const { rows: builderRows } = await client.query(
+      `SELECT status, rank FROM builders WHERE id = $1`,
+      [builderId]
+    );
+    if (builderRows[0] && builderRows[0].status === 'inactive') {
+      throw { code: 'BUILDER_INACTIVE' };
+    }
+    const builderRank = builderRows[0] ? builderRows[0].rank : null;
+
+    // Lock every requested task row up front (sorted to avoid deadlocks).
+    const { rows: taskRows } = await client.query(
+      `SELECT id, status, touches, newcomer_friendly, requires_rank, needs_migration, module_key, goal_id FROM tasks WHERE id = ANY($1::bigint[]) ORDER BY id FOR UPDATE`,
+      [uniqIds]
+    );
+
+    const failures = [];
+    // node-pg returns bigint/bigserial columns (tasks.id) as JS STRINGS, not
+    // numbers (learning #94) — Number() them before comparing against uniqIds
+    // (which are already numbers). Without this, foundIds.has(requestedId)
+    // never matches ("1781" !== 1781) and EVERY requested id is wrongly
+    // reported TASK_NOT_FOUND, even ones the SELECT above found fine.
+    const foundIds = new Set(taskRows.map((r) => Number(r.id)));
+    for (const requestedId of uniqIds) {
+      if (!foundIds.has(requestedId)) {
+        failures.push({ task_id: requestedId, reason: 'TASK_NOT_FOUND' });
+      }
+    }
+    for (const t of taskRows) {
+      if (t.status !== 'ready') {
+        failures.push({ task_id: t.id, reason: 'TASK_NOT_READY', currentStatus: t.status });
+      }
+    }
+
+    // task 1002650 (idea 1000644): same open-blocker rule as claimTask — the
+    // batch path must not sidestep the gate the feed and single claim enforce.
+    const { rows: blockedRows } = await client.query(
+      `SELECT tb.task_id, b.id, b.title
+         FROM task_blockers tb
+         JOIN blockers b ON b.id = tb.blocker_id
+        WHERE tb.task_id = ANY($1::bigint[])
+          AND b.status = 'open'
+        ORDER BY b.id`,
+      [uniqIds]
+    );
+    const blockersByTask = new Map();
+    for (const r of blockedRows) {
+      const list = blockersByTask.get(Number(r.task_id)) || [];
+      list.push({ id: r.id, title: r.title });
+      blockersByTask.set(Number(r.task_id), list);
+    }
+    for (const [blockedTaskId, blockers] of blockersByTask) {
+      failures.push({ task_id: blockedTaskId, reason: 'OPEN_BLOCKER', blockers });
+    }
+
+    // Three-rank model (task #360 / ADR 0018; V3.R15 #239): a Xenos may
+    // batch-claim only tasks explicitly opened to them (newcomer_friendly).
+    // Mirrors the single claimTask gate so the batch path can't be used to
+    // sidestep the sandbox. Failure reason carries both names — the new
+    // canonical code and the legacy alias — so callers on either release work.
+    //
+    // BV1.R106 (ADR 0151): the inner decision now reads the PERMISSION atoms, as
+    // in claimTask. The outer `builderRank === 'xenos'` short-circuit is LEFT AS
+    // IS: it is not a fast path but a semantic one (a reserved/unwired rank is
+    // never checked here, while claimTask checks every rank), so removing it would
+    // change who can batch-claim. That pre-existing asymmetry is reported, not
+    // fixed, under this task — closing it is an authority decision of its own.
+    if (builderRank === 'xenos') {
+      for (const t of taskRows) {
+        if (!claimEligibilityAllows({
+          heldPermissions,
+          newcomerFriendly: t.newcomer_friendly,
+          rankRuleAllows: xenosClaimAllowed(builderRank, t.newcomer_friendly),
+        })) {
+          failures.push({ task_id: t.id, reason: 'rank_too_low_for_task', legacy_reason: 'XENOS_RESTRICTED' });
+        }
+      }
+    }
+
+    // V3.R82 (#301): the per-task requires_rank floor. Mirrors the single
+    // claimTask gate so a Metic can't slip through batch-claim to grab an
+    // Archon-only task. The xenos sandbox check above handles the xenos case
+    // exhaustively for requires_rank='xenos' (the default); this gate refuses
+    // requires_rank='metic'/'archon' when the builder is below.
+    for (const t of taskRows) {
+      if (!rankAllowsTask(builderRank, t.requires_rank)) {
+        failures.push({
+          task_id: t.id,
+          reason: 'INSUFFICIENT_RANK',
+          required: t.requires_rank,
+          actual: builderRank,
+        });
+      }
+    }
+
+    // task 1003137: the SAME extracted goal-membership gate as claimTask — this
+    // path owns the repo's only other INSERT INTO claims, so an inline-only gate
+    // would be bypassable via batch. Same ladder position: after rank, before deps.
+    for (const f of await goalMembershipFailures({ client, tasks: taskRows, builderId, builderRank })) {
+      const { code, ...rest } = f.refusal;
+      failures.push({ task_id: f.task_id, reason: code, ...rest });
+    }
+
+    // Per-task dependency check (ADR 0015, generalized task 1516). An EXTERNAL dep
+    // (not in this batch) must already be done; a batch-internal dep isn't done yet
+    // at claim time but doesn't block — the batch is worked serially. "Internal"
+    // applies ONLY to task-kind deps: a goal/criterion dep can never be a task id in
+    // the batch, so it is always external (must not be filtered out).
+    const batchIdSet = new Set(uniqIds);
+    for (const t of taskRows) {
+      const unmet = await unsatisfiedDeps(t.id, client);
+      const external = unmet.filter((d) => !(d.kind === 'task' && batchIdSet.has(Number(d.id))));
+      if (external.length > 0) {
+        failures.push({
+          task_id: t.id,
+          reason: 'DEPS_NOT_SHIPPED',
+          deps: external.map((d) => ({ kind: d.kind, id: d.id, title: d.title, status: d.state })),
+        });
+      }
+    }
+
+    // BV1.R53 (task 1422): module-disjointness within the batch — two tasks in
+    // the same module are a hard conflict (batch is the autonomous --parallel
+    // path; module-disjointness is always enforced there).
+    for (let i = 0; i < taskRows.length; i++) {
+      for (let j = i + 1; j < taskRows.length; j++) {
+        const a = taskRows[i];
+        const b = taskRows[j];
+        if (a.module_key && b.module_key && a.module_key === b.module_key) {
+          failures.push({
+            task_id: b.id,
+            reason: 'MODULE_CONFLICT',
+            module_key: a.module_key,
+            conflictsWithTaskId: a.id,
+          });
+        }
+      }
+    }
+
+    // touches[] cleanup [5/8] (task 880): inter-batch overlap via the canonical
+    // prefix-aware matcher (was JS Set-equality, which missed dir-prefix
+    // adjacency like ['src/bongos/'] vs ['src/bongos/db.js']). Batch claims are the
+    // autonomous --parallel path, so the overlap gate stays HARD here.
+    // Skip the touches check for pairs where both tasks have module_key set —
+    // module-disjointness already covers them (either same-module = conflict above,
+    // or different-module = always safe regardless of predicted file paths).
+    for (let i = 0; i < taskRows.length; i++) {
+      for (let j = i + 1; j < taskRows.length; j++) {
+        const a = taskRows[i];
+        const b = taskRows[j];
+        if (a.module_key && b.module_key) continue; // module-disjointness handled above
+        if (touchesOverlap(a.touches, b.touches)) {
+          failures.push({
+            task_id: b.id,
+            reason: 'BATCH_TOUCHES_CONFLICT',
+            conflictsWithTaskId: a.id,
+          });
+        }
+      }
+    }
+
+    // Touches conflict against OTHER builders' active claims (prefix-aware).
+    // Fetch every active claim's touches (can't SQL-prefilter with `&&` — that
+    // would miss dir-prefix adjacency) and compare with the canonical matcher.
+    const { rows: activeClaims } = await client.query(
+      `SELECT c.id AS claim_id, c.task_id AS conflict_task_id, t.title, t.touches, t.module_key
+         FROM claims c
+         JOIN tasks t ON t.id = c.task_id
+        WHERE c.released_at IS NULL
+          AND t.id <> ALL($1::bigint[])`,
+      [uniqIds]
+    );
+    for (const t of taskRows) {
+      // BV1.R53: module-disjointness against other builders' active claims.
+      if (t.module_key) {
+        for (const cr of activeClaims) {
+          if (cr.module_key === t.module_key) {
+            failures.push({
+              task_id: t.id,
+              reason: 'MODULE_CONFLICT',
+              module_key: t.module_key,
+              conflictTaskTitle: cr.title,
+              conflictClaimId: cr.claim_id,
+            });
+          }
+        }
+      }
+      for (const cr of activeClaims) {
+        if (t.module_key && cr.module_key) continue; // both have module_key → handled above
+        if (touchesOverlap(t.touches, cr.touches)) {
+          failures.push({
+            task_id: t.id,
+            reason: 'TOUCHES_CONFLICT',
+            conflictTaskTitle: cr.title,
+            conflictClaimId: cr.claim_id,
+          });
+        }
+      }
+    }
+
+    if (failures.length > 0) {
+      throw { code: 'BATCH_FAILED', failures };
+    }
+
+    // All checks passed. Insert N claim rows, allocating per-task migration
+    // numbers if the touches[] signals it. The unique-violation safety net is
+    // still here: if another batch beat us to a row between our SELECT FOR
+    // UPDATE and INSERT (it can't, given the row lock, but defense in depth),
+    // we surface that as ALREADY_CLAIMED for the specific task.
+    //
+    // task 1802 — uniq_active_claim_per_session (migration 180) was keyed on
+    // creator_session_id alone, so it couldn't tell "N rows from one batch call"
+    // from "N rows from N separate /claims calls": every row here used to carry
+    // the SAME non-null creatorSessionId for a real (bound) CLI session, so the
+    // 2nd INSERT always hit the partial unique index. (core_204 / task
+    // 1002570 re-keyed it per (session, worktree) — but a prefix-less batch
+    // stores NULL worktree_name on every row, which the index folds into ONE
+    // group, so first-row-only binding stays load-bearing.) Each batch-claimed task
+    // also gets its OWN worktree name (worktreePrefix-taskId, right below) — a
+    // batch is claiming N tasks for N future (possibly parallel) working
+    // sessions, not one shared worktree — so there is no correctness reason to
+    // bind every row to the session that placed the batch call. Bind only the
+    // FIRST row (preserves today's exact behavior for the common size-1 batch,
+    // and keeps this session's own "at most one BOUND active claim" invariant
+    // intact); every later row in the batch is inserted session-unbound
+    // (creator_session_id=NULL), same as a bind_session:false web claim —
+    // adoptable by any of the builder's own CLI sessions when they pick it up.
+    const inserted = [];
+    for (let i = 0; i < taskRows.length; i++) {
+      const t = taskRows[i];
+      let reservedMigrationNumber = null;
+      if (t.needs_migration === true) {
+        const { rows: bumpRows } = await client.query(
+          `UPDATE migration_counter
+              SET next_number = next_number + 1
+            WHERE id = 1
+            RETURNING next_number - 1 AS allocated`
+        );
+        reservedMigrationNumber = bumpRows[0].allocated;
+      }
+      // task 1002522: fold the prefix the same way a single claim's name is
+      // folded, so a blank/whitespace prefix yields worktree-less rows rather
+      // than names like "  -1234" that the index would key as distinct trees.
+      const foldedPrefix = foldWorktreeName(worktreePrefix);
+      const worktreeName = foldedPrefix
+        ? `${foldedPrefix}-${t.id}`
+        : null;
+      const rowCreatorSessionId = i === 0 ? (creatorSessionId ?? null) : null;
+      try {
+        // task 1002709: requested == final on this path by construction — each
+        // row gets its own `<prefix>-<taskId>` tree and nothing disambiguates
+        // them. It is still written explicitly rather than left NULL: core_221's
+        // index keys on COALESCE(requested_worktree_name, ''), so a NULL here
+        // would make a row that HAS a worktree read as worktree-less and collide
+        // with the shared-clone group.
+        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, $3, NULL, $4, $5)
+           RETURNING id, task_id, builder_id, worktree_name, requested_worktree_name, claimed_at, head_sha, reserved_migration_number`,
+          [t.id, builderId, worktreeName, reservedMigrationNumber, rowCreatorSessionId]
+        );
+        inserted.push(insertClaim.rows[0]);
+      } catch (err) {
+        if (err && err.code === '23505') {
+          // task 1002589: same constraint branch as claimTask — the per-session
+          // index can trip here on the FIRST (bound) row when the calling
+          // session already holds a bound claim; every other 23505 stays the
+          // per-task race answer.
+          throw { code: 'BATCH_FAILED', failures: [{ task_id: t.id, reason: claimUniqueViolationError(err).code }] };
+        }
+        throw err;
+      }
+      await client.query(`UPDATE tasks SET status = 'active' WHERE id = $1`, [t.id]);
+    }
+
+    await client.query('COMMIT');
+    return { claims: inserted };
+  } catch (err) {
+    await client.query('ROLLBACK').catch(() => {});
+    throw err;
+  } finally {
+    client.release();
+  }
+}
+
+// Bulk release (task 1758): release N of the caller's OWN claims in one call —
+// the batch twin of the single-claim resolve(outcome='abandoned') path
+// (release.js / the work board's doRelease both use that path; this is the
+// same effect, N at a time). Unlike claimTasksBatch, this is NOT all-or-nothing:
+// a release has no cross-claim invariant to protect (no touches/module/
+// dependency check makes sense between two claims being given back), so each
+// claim_id stands alone. One bad id (not found, not yours, already resolved,
+// session-locked) fails ONLY that item — every other valid id in the batch
+// still releases. Mirrors resolveClaim's per-claim effects (released_at +
+// outcome, task → 'ready', sealSessionLog, actual_minutes recompute) and
+// releaseClaimOnBehalf's row-locked batch-read shape.
+async function releaseClaimsBatch({ claimIds, builderId, resolverSessionId, force }) {
+  if (!Array.isArray(claimIds) || claimIds.length === 0) {
+    throw { code: 'BATCH_EMPTY' };
+  }
+  // Stable-sort before locking so two concurrent batches sharing a row can't
+  // deadlock by locking in opposite orders (claimTasksBatch precedent).
+  const uniqIds = Array.from(new Set(claimIds.map(Number))).sort((a, b) => a - b);
+
+  return withTx(async (client) => {
+    const { rows: claimRows } = await client.query(
+      `SELECT c.id, c.task_id, c.builder_id, c.released_at, c.claimed_at,
+              c.worktree_name, c.creator_session_id, t.title
+         FROM claims c JOIN tasks t ON t.id = c.task_id
+        WHERE c.id = ANY($1::bigint[]) FOR UPDATE`,
+      [uniqIds]
+    );
+    // node-pg returns claims.id (bigserial) as a STRING (learning #94) — Number()
+    // it so lookups below (byId.get(claimId), claimId from uniqIds) actually hit.
+    const byId = new Map(claimRows.map((r) => [Number(r.id), r]));
+
+    const released = [];
+    const failures = [];
+    for (const claimId of uniqIds) {
+      const claim = byId.get(claimId);
+      if (!claim) { failures.push({ claim_id: claimId, reason: 'CLAIM_NOT_FOUND' }); continue; }
+      if (claim.builder_id !== builderId) { failures.push({ claim_id: claimId, reason: 'NOT_YOUR_CLAIM' }); continue; }
+      if (claim.released_at) { failures.push({ claim_id: claimId, reason: 'ALREADY_RESOLVED' }); continue; }
+      if (!force && claim.creator_session_id && resolverSessionId &&
+          claim.creator_session_id !== resolverSessionId) {
+        failures.push({ claim_id: claimId, reason: 'CLAIM_SESSION_MISMATCH', claimWorktree: claim.worktree_name ?? null });
+        continue;
+      }
+
+      await client.query(
+        `UPDATE claims SET released_at = now(), outcome = 'abandoned' WHERE id = $1`,
+        [claimId]
+      );
+      await client.query(
+        // ADR 0120 part 2: releasing a task frees it from the builder's queue,
+        // so clear any needs_rebase flag — the rebase is no longer their chore
+        // (this is the "release to unblock" exit the ADR guarantees).
+        `UPDATE tasks
+            SET status = 'ready', needs_rebase = false, needs_rebase_reason = NULL,
+                needs_rebase_at = NULL, updated_at = now()
+          WHERE id = $1`,
+        [claim.task_id]
+      );
+      await sealSessionLog(client, {
+        builderId, taskId: claim.task_id, claimId, startedAt: claim.claimed_at,
+        outcome: 'abandoned', notesMd: null,
+      });
+      await client.query(
+        `UPDATE tasks
+            SET actual_minutes = (
+              SELECT COALESCE(SUM(EXTRACT(EPOCH FROM (ended_at - started_at)) / 60)::integer, 0)
+              FROM session_logs WHERE task_id = $1
+            )
+          WHERE id = $1`,
+        [claim.task_id]
+      );
+      released.push({ claim_id: claimId, task_id: claim.task_id, task_title: claim.title });
+    }
+
+    return { released, failures };
+  });
+}
+
+// Read-only dry-run twin of claimTasksBatch's pre-flight checks (task 1758).
+// Validates an arbitrary task_id set for parallel-safety + sequencing WITHOUT
+// claiming anything — no row lock, no write — so the hall's multi-select
+// toolbar can grey out invalid actions before a real claim. Mirrors
+// claimTasksBatch's checks (rank, dependencies, module-disjointness, touches
+// overlap — both within the set and against other builders' active claims)
+// but collects EVERY failure per task instead of stopping at the first one.
+// Keep the check set in sync with claimTasksBatch if either changes.
+async function validateClaimBatch({ taskIds, builderId }) {
+  if (!Array.isArray(taskIds) || taskIds.length === 0) {
+    throw { code: 'BATCH_EMPTY' };
+  }
+  const uniqIds = Array.from(new Set(taskIds.map(Number)));
+
+  const { rows: builderRows } = await pool.query(
+    `SELECT status, rank FROM builders WHERE id = $1`,
+    [builderId]
+  );
+  const builderInactive = builderRows[0] ? builderRows[0].status === 'inactive' : false;
+  const builderRank = builderRows[0] ? builderRows[0].rank : null;
+
+  const { rows: taskRows } = await pool.query(
+    `SELECT id, status, touches, newcomer_friendly, requires_rank, module_key, goal_id
+       FROM tasks WHERE id = ANY($1::bigint[])`,
+    [uniqIds]
+  );
+  // node-pg returns tasks.id (bigserial) as a STRING (learning #94) — Number()
+  // it so lookups below (byId.get(id), id from uniqIds) actually hit.
+  const byId = new Map(taskRows.map((r) => [Number(r.id), r]));
+
+  // Other builders' active claims — for the cross-batch touches/module check,
+  // same query shape as claimTasksBatch.
+  const { rows: activeClaims } = await pool.query(
+    `SELECT c.id AS claim_id, t.title, t.touches, t.module_key
+       FROM claims c JOIN tasks t ON t.id = c.task_id
+      WHERE c.released_at IS NULL AND t.id <> ALL($1::bigint[])`,
+    [uniqIds]
+  );
+
+  const reasonsById = new Map(uniqIds.map((id) => [id, []]));
+  const push = (id, reason) => reasonsById.get(id).push(reason);
+
+  // BV1.R106: same permission-expressed queue gate as claimTasksBatch (including
+  // its `builderRank === 'xenos'` short-circuit), resolved once for the whole set
+  // — authority is per-request, not per-row.
+  const heldPermissions = await claimPermissionsFor(builderId);
+
+  for (const id of uniqIds) {
+    if (builderInactive) push(id, { reason: 'BUILDER_INACTIVE' });
+    const t = byId.get(id);
+    if (!t) { push(id, { reason: 'TASK_NOT_FOUND' }); continue; }
+    if (t.status !== 'ready') push(id, { reason: 'TASK_NOT_READY', currentStatus: t.status });
+    if (builderRank === 'xenos' && !claimEligibilityAllows({
+      heldPermissions,
+      newcomerFriendly: t.newcomer_friendly,
+      rankRuleAllows: xenosClaimAllowed(builderRank, t.newcomer_friendly),
+    })) {
+      push(id, { reason: 'rank_too_low_for_task', legacy_reason: 'XENOS_RESTRICTED' });
+    }
+    if (!rankAllowsTask(builderRank, t.requires_rank)) {
+      push(id, { reason: 'INSUFFICIENT_RANK', required: t.requires_rank, actual: builderRank });
+    }
+  }
+
+  // task 1003137: goal-membership, kept in sync with claimTasksBatch (see claim-feed.js).
+  for (const f of await goalMembershipFailures({ client: pool, tasks: taskRows, builderId, builderRank })) {
+    const { code, ...rest } = f.refusal;
+    push(f.task_id, { reason: code, ...rest });
+  }
+
+  // Dependencies — external to the batch only (a batch-internal dep is fine;
+  // the batch is worked serially, same rule as claimTasksBatch).
+  const batchIdSet = new Set(uniqIds);
+  for (const id of uniqIds) {
+    if (!byId.get(id)) continue;
+    const unmet = await unsatisfiedDeps(id);
+    const external = unmet.filter((d) => !(d.kind === 'task' && batchIdSet.has(Number(d.id))));
+    if (external.length > 0) {
+      push(id, {
+        reason: 'DEPS_NOT_SHIPPED',
+        deps: external.map((d) => ({ kind: d.kind, id: d.id, title: d.title, status: d.state })),
+      });
+    }
+  }
+
+  // Cross-task conflicts within the set — module-disjointness, then touches
+  // overlap. Symmetric: a conflicting pair marks BOTH task_ids invalid for
+  // PARALLEL (either can still run alone / sequentially after the other).
+  for (let i = 0; i < uniqIds.length; i++) {
+    const a = byId.get(uniqIds[i]);
+    if (!a) continue;
+    for (let j = i + 1; j < uniqIds.length; j++) {
+      const b = byId.get(uniqIds[j]);
+      if (!b) continue;
+      if (a.module_key && b.module_key && a.module_key === b.module_key) {
+        push(a.id, { reason: 'MODULE_CONFLICT', module_key: a.module_key, conflictsWithTaskId: b.id });
+        push(b.id, { reason: 'MODULE_CONFLICT', module_key: a.module_key, conflictsWithTaskId: a.id });
+        continue;
+      }
+      if (a.module_key && b.module_key) continue;
+      if (touchesOverlap(a.touches, b.touches)) {
+        push(a.id, { reason: 'BATCH_TOUCHES_CONFLICT', conflictsWithTaskId: b.id });
+        push(b.id, { reason: 'BATCH_TOUCHES_CONFLICT', conflictsWithTaskId: a.id });
+      }
+    }
+  }
+
+  // Conflicts against OTHER builders' active claims (prefix-aware touches +
+  // module-disjointness) — the check the client can't do on its own, since it
+  // has no visibility into claims it doesn't hold.
+  for (const id of uniqIds) {
+    const t = byId.get(id);
+    if (!t) continue;
+    for (const cr of activeClaims) {
+      if (t.module_key && cr.module_key === t.module_key) {
+        push(id, { reason: 'MODULE_CONFLICT', module_key: t.module_key, conflictTaskTitle: cr.title, conflictClaimId: cr.claim_id });
+        continue;
+      }
+      if (t.module_key && cr.module_key) continue;
+      if (touchesOverlap(t.touches, cr.touches)) {
+        push(id, { reason: 'TOUCHES_CONFLICT', conflictTaskTitle: cr.title, conflictClaimId: cr.claim_id });
+      }
+    }
+  }
+
+  const results = uniqIds.map((id) => {
+    const reasons = reasonsById.get(id);
+    return { task_id: id, valid: reasons.length === 0, reasons };
+  });
+
+  return { results, parallel_safe: results.every((r) => r.valid) };
+}
+
+module.exports = {
+  claimTask,
+  claimTasksBatch,
+  claimUniqueViolationError,
+  releaseClaimsBatch,
+  validateClaimBatch,
+};