@bongos/core 1.19.253 → 1.19.254

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.253",
-  "core_contract": "1.19.253",
-  "source_commit": "7e98077a8a33b1ef861ab40823c1db64acffc71d",
+  "core_version": "1.19.254",
+  "core_contract": "1.19.254",
+  "source_commit": "5955d399c73ae928fb94ecf67c3c1a59f2688dcd",
   "source_ref": "HEAD",
-  "built_at": "2026-08-19T01:42:12.781Z",
+  "built_at": "2026-08-19T02:09:24.775Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 315,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1345,
+    "functional_verbatim": 1347,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1682,
-  "tree_sha256": "942f711051e57b17995dbd18b2ee81dee4466440acb5c3559659f72b4e0291ba",
+  "file_count": 1684,
+  "tree_sha256": "a11f4b0d4a9487d13e0c01a48dcf28c80f4f008045403cc5388cb40c72bd3462",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -947,7 +947,7 @@
     {
       "path": "docs/adr/0097-one-active-claim-per-session-and-worktree-binding.md",
       "mode": "0000644",
-      "sha256": "3aa1e9074bd62168f999139533d672b0e0369186e2a78bbc966bca940df8d012"
+      "sha256": "e06b7b9a18b669d1bc584ae0db73ccf49b47962580f632f8492113cca623bf37"
     },
     {
       "path": "docs/adr/0097-retroactive-reward-backfill.md",
@@ -2399,6 +2399,11 @@
       "mode": "0000644",
       "sha256": "e0503f677b4b30eca07badd76ba9b177f603f3740da366c1be40cb67a5537690"
     },
+    {
+      "path": "migrations/core_221_claims_requested_worktree_name.sql",
+      "mode": "0000644",
+      "sha256": "51d7fc76fdc59a5ab145839aa4943fe7753324022f82e4b4a76c2fe3cab9b98d"
+    },
     {
       "path": "modules/autonomy/CLAUDE.md",
       "mode": "0000644",
@@ -3702,7 +3707,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "ed948712d57d984684313afd0160b1838c8cde061f82bd62f31226e39b8df122"
+      "sha256": "b35b53b3badf7f465fe97d317cd32653518f14d98a76a03b18374c49b31db65a"
     },
     {
       "path": "modules/lifecycle/done-when.js",
@@ -3777,7 +3782,7 @@
     {
       "path": "modules/lifecycle/routes/claims.js",
       "mode": "0000644",
-      "sha256": "60f698b88fab3b850e2ab7d4350b7192ca57fa932089d0a24a187add08e5c819"
+      "sha256": "4f40c6e74c40c1ff29f8f487e2a6b574e7998aca4366a6372101d17412917eea"
     },
     {
       "path": "modules/lifecycle/routes/dependencies.js",
@@ -4432,12 +4437,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ade08bd4afada8f234fdb5bd155ad37628bc01040f76de7a378356d338933721"
+      "sha256": "c880668f9420934895a29f1442f4db984dbaea35a93de7399f97353d6e5356f9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2278bb9510a79406d9ee34e9662df8a81273343075d382d7241b0f360650d199"
+      "sha256": "80552b01c8d22ddfa1f5bf0e479dfe27c4e62e2e932555237f418bbe18edfd22"
     },
     {
       "path": "public-docs/index.html",
@@ -5427,7 +5432,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "96e8495ffded28083ba458e8d527c5ba25793a20d5f4c0fee5160cff778f4def"
+      "sha256": "e2e3cd6299f63b838ed5a78121eedcb44e76b3cc62b622581cd537c154b1d8ae"
     },
     {
       "path": "scripts/gds/sandbox-stage.js",
@@ -6057,7 +6062,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a12419c00b425a6b98a646cb98e5d20584863185779453e88c52c7036ac1ff62"
+      "sha256": "0f52e5cbb0bc88abd77cdc790b563c8a2766ed6d4a5a73240343b15655f07442"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6509,6 +6514,11 @@
       "mode": "0000644",
       "sha256": "d8d95c67c6c746418716b384fc46eefbf5187686f091353258768b83d5c44519"
     },
+    {
+      "path": "tests/claims_requested_worktree_db.mjs",
+      "mode": "0000644",
+      "sha256": "977e10f8a92acf20afa58c01bd2d0b68d64414ac7d2a1d15a4d22c332be75f36"
+    },
     {
       "path": "tests/claude_materialize.mjs",
       "mode": "0000644",
@@ -7667,7 +7677,7 @@
     {
       "path": "tests/one_active_claim_per_session.mjs",
       "mode": "0000644",
-      "sha256": "030c7f3958d1fef45977326b52596e21638fe80b4ff9e7ecba31c76063283aea"
+      "sha256": "f4da7e663ab6d7b93bb02ecefd18178fa654a314da07108c4316317f50115ad0"
     },
     {
       "path": "tests/orphaned_claim_ship.mjs",

package/docs/adr/0097-one-active-claim-per-session-and-worktree-binding.md

@@ -42,11 +42,21 @@ The default claim flow (`.claude/skills/builder-claim/SKILL.md`) ensures the tas
 
 > **Amended 2026-08-11 (task 1002522) — the guard and the index now fold tree identity identically.** `core_204`'s key folds `NULL` and `''` together (`COALESCE(worktree_name, '')`); the guard compared raw values, where `'' !== null`. So a claim sent with `worktree_name: ""` (the route caps the length but never required non-empty) was waved through beside a worktree-less claim and *then* refused by the index — a `23505` on a task nobody had taken. `db.foldWorktreeName` is now the single normalization: it folds empty/whitespace-only to `NULL` and trims, and it is applied at **every ingest point** (`claimTask`, `claimTasksBatch`'s prefix, and `shouldRefuseSessionClaim`), so stored names are always trimmed-or-`NULL` and the guard's comparison of stored rows is exact by construction. Pinned DB-free in `tests/one_active_claim_per_session.mjs`.
 >
-> Two things were checked and deliberately left alone. **The stale-claim sweep needs no re-tuning** now that one session may hold N claims: both the heartbeat (`session_pulses`, PK `claim_id`) and the sweep (`modules/sessions/pulse.js sweepStaleClaims`) are keyed per *claim*, never per session, so each parallel worktree's claim ages out on its own clock. **One residual divergence remains**, tracked as [#1002709](https://example.com/builders#/task/1002709): V3.R51 disambiguation renames a colliding `worktree_name` (`"wt-a"` → `"wt-a-2"`) while the CLI keeps sending the original, so guard and index both key on a name the caller never used — a second claim in the *same* real tree can slip past both. Closing it needs the requested name persisted (a schema decision), which is why it is a follow-up rather than part of this amendment.
+> Two things were checked and deliberately left alone. **The stale-claim sweep needs no re-tuning** now that one session may hold N claims: both the heartbeat (`session_pulses`, PK `claim_id`) and the sweep (`modules/sessions/pulse.js sweepStaleClaims`) are keyed per *claim*, never per session, so each parallel worktree's claim ages out on its own clock. **One residual divergence remains**, tracked as [#1002709](https://example.com/builders#/task/1002709): V3.R51 disambiguation renames a colliding `worktree_name` (`"wt-a"` → `"wt-a-2"`) while the CLI keeps sending the original, so guard and index both key on a name the caller never used — a second claim in the *same* real tree can slip past both. Closing it needs the requested name persisted (a schema decision), which is why it is a follow-up rather than part of this amendment. **That follow-up landed — see the next amendment.**
 
 ## Consequences
 
 - A session can hold at most one active claim — commingled ships are structurally prevented, not just discouraged.
+> **Amended 2026-08-19 (task 1002709 / `core_221`) — the residual divergence above is closed: the guard keys on the REQUESTED worktree name.** V3.R51 disambiguation silently renames a colliding `worktree_name` (`"overnight"` → `"overnight-2"`), which is correct and load-bearing — `.claude/worktrees/<name>` is a filesystem path and two live builders pointing at one would stomp each other. But both halves of the rule then keyed on the **stored** name while `scripts/gds/claim.js` keeps sending the **real directory** name, which is never renamed. So a second claim from the same session in the same tree compared `"overnight"` against the stored `"overnight-2"`, read them as two trees, and was allowed by the guard *and* the index: one working tree, one branch, two active claims — precisely the commingled ship this ADR exists to prevent. Reachable for any fixed reusable name (the overnight builder, box workflows, a hand-passed `--worktree`).
+>
+> `claims.requested_worktree_name` now stores what the caller asked for, and the guard (`shouldRefuseSessionClaim`) plus the re-keyed index `uniq_active_claim_per_session_requested_worktree` both key on it. **Two names, two jobs, and keeping them apart is the point:** `worktree_name` is the disambiguated name on disk and stays globally unique across active claims (branch naming and the operator surfaces read it); `requested_worktree_name` is the identity of the working *tree*, which is what "do these two claims share a tree" actually asks.
+>
+> **Why a stored column and not a cleverer guard.** Matching `^<requested>-\d+$` would refuse a builder genuinely running worktrees `foo` and `foo-2` side by side — reintroducing exactly the false refusal this family of amendments (1002570, 1002589, 1002522) keeps having to undo. The guard needs the name the claim was *filed* under, and that was simply never recorded.
+>
+> **The migration deliberately UNDER-heals, and that is a decision rather than an oversight.** After the backfill copies `worktree_name` across, a pre-existing commingled pair (stored `overnight` + `overnight-2`, one real tree) and a legitimate pair (stored `foo` + `foo-2`, two real trees) are **indistinguishable** — the requested name was never recorded, which is the whole bug. Any heuristic able to close the first would also silently close the second, killing an active claim of a builder who did nothing wrong, and a migration acts without asking. So pairs already in flight stay in flight (the pre-existing hazard, unchanged: the first to ship takes the branch), and no *new* pair can be created from the moment the guard lands. The heal still earns its place for rows the new code writes, where a genuine collision on the requested name is possible and would otherwise block `CREATE UNIQUE INDEX` on deploy.
+>
+> All three index generations stay in `claimUniqueViolationError`'s `SESSION_CLAIM_INDEXES`, because a deploy applies code and migration at different instants and an unrecognised constraint falls closed onto the generic `ALREADY_CLAIMED` — the phantom-rival answer task 1002589 removed. The guard falls back to `worktree_name` when `requested_worktree_name` is NULL, which keeps it correct in that same window. Pinned DB-free in `tests/one_active_claim_per_session.mjs` (including the three-step repro, which fails against the old code) and against a real Postgres in `tests/claims_requested_worktree_db.mjs`.
+
 - The many-sessions-per-builder norm (ADR 0049's `feedback_parallel_sessions_not_anomaly`) is preserved exactly: each worktree/session still gets its own claim.
 - Web claims (NULL session) are unaffected — claim-in-browser, ship-from-any-terminal still works.
 - This composes with, and does not alter, ADR 0049's split cross-claim contract: the per-task index, the advisory `touches[]` warning, and the autonomous-runner footprint gate are all untouched. This ADR only adds the within-session invariant 0049 left implicit.

package/migrations/core_221_claims_requested_worktree_name.sql

@@ -0,0 +1,144 @@
+-- core_221_claims_requested_worktree_name.sql
+-- Task 1002709 (goal 1000024, build-pipeline integrity). A CORE migration, not a
+-- lifecycle_ one, by the same rule core_204 states: it alters the shared
+-- pre-module `claims` table and swaps an index on it, and a module migration
+-- must stay additive within its own <key>_ tables (ADR 0083 §Decision #5).
+-- Idempotent on re-run.
+--
+-- ── THE HOLE ────────────────────────────────────────────────────────────────
+--
+-- V3.R51 disambiguation (modules/lifecycle/db.js disambiguateWorktreeName)
+-- silently RENAMES a requested worktree_name that collides with any other
+-- currently-active claim: "overnight" is stored as "overnight-2". That rename is
+-- correct and load-bearing — `.claude/worktrees/<name>` is a filesystem path and
+-- two live builders pointing at one would stomp each other.
+--
+-- But both halves of the one-claim-per-tree rule then key on the STORED name,
+-- while the CLI keeps sending the REQUESTED one (scripts/gds/claim.js reads the
+-- real directory, which is never renamed). So:
+--
+--   1. Builder X holds an active claim with worktree_name "overnight".
+--   2. Builder Y, session S, in a tree genuinely named "overnight", claims task
+--      A. Y's name collides with X's, so it is stored as "overnight-2".
+--   3. Same session S, same tree, claims task B. The guard compares the incoming
+--      "overnight" against the stored "overnight-2" — different tree, ALLOW. The
+--      index sees (S,"overnight") vs (S,"overnight-2") — no collision, INSERT.
+--
+-- Result: ONE real working tree, ONE branch, TWO active claims — the exact
+-- commingled-ship hazard task 1642 and ADR 0097 exist to prevent. Rare, because
+-- worktree names are usually task-slug + random hex, but reachable for any fixed
+-- reusable name: the overnight builder, box workflows, `--worktree` passed by
+-- hand.
+--
+-- ── WHY A COLUMN AND NOT A CLEVERER GUARD ───────────────────────────────────
+--
+-- Matching "^<requested>-\d+$" in the guard would refuse a builder who genuinely
+-- runs worktrees "foo" and "foo-2" side by side — reintroducing the false
+-- refusal this whole family of bugs (1002570, 1002589, 1002522) is about. The
+-- guard needs the name the claim was FILED under, which is simply not stored
+-- today. So store it.
+--
+-- TWO NAMES, TWO JOBS, and keeping them separate is the point:
+--   worktree_name            the name on DISK after disambiguation. Still what
+--                            branch naming and the operator surfaces read, and
+--                            still globally unique across active claims.
+--   requested_worktree_name  the name the CALLER asked for. The identity of the
+--                            working TREE, which is what "do these two claims
+--                            share a tree" actually asks.
+--
+-- ── THE BACKFILL IS HONEST ABOUT WHAT IT CANNOT KNOW ────────────────────────
+--
+-- For historical rows the requested name was never recorded. Copying
+-- worktree_name across is exactly right for every row that was NOT renamed (the
+-- overwhelming majority — disambiguation only fires on a live collision) and is
+-- the best available answer for the few that were. It cannot resurrect a lost
+-- fact, and it does not pretend to: the column is nullable, and a row that was
+-- renamed simply carries its post-rename name as its pre-rename one. No active
+-- claim changes meaning, because the pair is only compared against other rows
+-- backfilled the same way.
+
+BEGIN;
+
+ALTER TABLE claims
+  ADD COLUMN IF NOT EXISTS requested_worktree_name text;
+
+COMMENT ON COLUMN claims.requested_worktree_name IS
+  'The worktree name the CALLER asked for, before V3.R51 disambiguation renamed it. The one-claim-per-working-tree guard keys on THIS (task 1002709); worktree_name remains the disambiguated on-disk name.';
+
+-- Backfill (see the header): the requested name equals the stored name for every
+-- row disambiguation never touched, and is the closest available answer for the
+-- rest. Guarded so a re-run never overwrites a real value with a stale one.
+UPDATE claims
+   SET requested_worktree_name = worktree_name
+ WHERE requested_worktree_name IS NULL;
+
+-- ── heal before CREATE (the migration 174/180/204 shape) ────────────────────
+--
+-- A unique index refuses to create if live rows already violate it, which would
+-- block the deploy. This heal keeps that safe for rows the NEW code writes.
+--
+-- WHAT IT CANNOT DO, STATED PLAINLY: it cannot find a commingled pair that
+-- already exists. Consider the two shapes, after the backfill above:
+--
+--   commingled   session S, stored "overnight" + "overnight-2", ONE real tree
+--   legitimate   session S, stored "foo"       + "foo-2",       TWO real trees
+--
+-- Both backfill to requested = their stored name, so both read as two distinct
+-- trees, and the heal closes neither. They are INDISTINGUISHABLE in the data —
+-- the requested name was never recorded, which is the entire bug. Any heuristic
+-- that could close the first (stripping a "-\d+" suffix) would also close the
+-- second, silently killing an active claim of a builder who did nothing wrong.
+-- That is the same false-refusal trap that makes suffix-matching wrong in the
+-- guard, and it is worse here because a migration acts without asking.
+--
+-- So this deliberately under-heals. The window it leaves is bounded and small:
+-- any commingled pair already in flight stays in flight, and the FIRST of the
+-- two to ship takes the tree's branch — the pre-existing hazard, unchanged. From
+-- the moment the new guard code lands, no NEW pair can be created. Closing the
+-- ledger honestly beats closing someone's claim on a guess.
+--
+-- The heal still earns its place: once rows carry a real requested name, two of
+-- them CAN collide on it, and then this closes the later and keeps the earliest
+-- — the same rule core_204 applied, and the one the guard would have applied had
+-- it been able to see the collision at claim time.
+WITH ranked AS (
+  SELECT c.id,
+         ROW_NUMBER() OVER (
+           PARTITION BY c.creator_session_id, COALESCE(c.requested_worktree_name, '')
+           ORDER BY c.claimed_at, c.id
+         ) AS rn
+    FROM claims c
+   WHERE c.released_at IS NULL
+     AND c.creator_session_id IS NOT NULL
+)
+UPDATE claims c
+   SET released_at = now(),
+       outcome     = COALESCE(c.outcome, 'abandoned')
+  FROM ranked r
+ WHERE c.id = r.id
+   AND r.rn > 1;
+
+-- ── swap the index ──────────────────────────────────────────────────────────
+-- COALESCE, not PG15's NULLS NOT DISTINCT, and it is load-bearing for the same
+-- reason core_204 gives: in a plain multi-column unique index NULLs are
+-- DISTINCT, so two worktree-less claims (one shared clone, whose single branch
+-- genuinely commingles) would both insert and re-open the hole task 1642 closed.
+--
+-- The old index is DROPPED rather than left alongside. Keeping it would re-refuse
+-- a legitimate second claim from a builder genuinely running "foo" and "foo-2"
+-- in parallel — the false refusal this change exists to avoid reintroducing.
+DROP INDEX IF EXISTS uniq_active_claim_per_session_worktree;
+
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_active_claim_per_session_requested_worktree
+  ON claims (creator_session_id, (COALESCE(requested_worktree_name, '')))
+  WHERE released_at IS NULL AND creator_session_id IS NOT NULL;
+
+-- (This index name and claimUniqueViolationError's SESSION_CLAIM_INDEXES set
+-- must stay in lockstep — tests/one_active_claim_per_session.mjs pins both
+-- sides, and all three generations stay in that set because a deploy applies
+-- code and migration at different instants.)
+
+INSERT INTO schema_migrations (version) VALUES ('core_221_claims_requested_worktree_name')
+  ON CONFLICT (version) DO NOTHING;
+
+COMMIT;

package/modules/lifecycle/db.js

@@ -2600,7 +2600,13 @@ async function unsatisfiedDeps(taskId, client = pool) {
 // 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, worktree)
+  '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
@@ -2830,7 +2836,18 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     // 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.
-    let finalWorktreeName = foldWorktreeName(worktreeName);
+    // 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
@@ -2841,10 +2858,10 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     }
 
     const insertClaim = await client.query(
-      `INSERT INTO claims (task_id, builder_id, worktree_name, head_sha, reserved_migration_number, creator_session_id)
-       VALUES ($1, $2, $3, $4, $5, $6)
-       RETURNING id, task_id, builder_id, worktree_name, claimed_at, head_sha, reserved_migration_number`,
-      [taskId, builderId, finalWorktreeName, headSha ?? null, reservedMigrationNumber, creatorSessionId ?? null]
+      `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]);
@@ -3198,10 +3215,16 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
         : 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, head_sha, reserved_migration_number, creator_session_id)
-           VALUES ($1, $2, $3, NULL, $4, $5)
-           RETURNING id, task_id, builder_id, worktree_name, claimed_at, head_sha, reserved_migration_number`,
+          `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]);
@@ -4843,7 +4866,12 @@ async function activeClaimCountForBuilder(builderId, deps = {}) {
 async function getActiveClaimsForSession(creatorSessionId) {
   if (!creatorSessionId) return [];
   const { rows } = await pool.query(
-    `SELECT c.id AS claim_id, c.task_id, c.creator_session_id, c.worktree_name, c.claimed_at,
+    // task 1002709: requested_worktree_name rides along because the guard keys on
+    // it — comparing the incoming REQUESTED name against a stored DISAMBIGUATED
+    // one is what let a second same-tree claim through. worktree_name stays
+    // selected: callers still render the on-disk name.
+    `SELECT c.id AS claim_id, c.task_id, c.creator_session_id, c.worktree_name,
+            c.requested_worktree_name, c.claimed_at,
             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

package/modules/lifecycle/routes/claims.js

@@ -90,13 +90,31 @@ function shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId, wo
   // Two claims share a WORKING TREE iff their folded worktree_names match — which
   // includes both being worktree-less (a plain clone, whose single branch
   // genuinely commingles).
-  const sameWorkingTree = (name) => db.foldWorktreeName(name) === incomingTree;
+  //
+  // task 1002709: compare against the REQUESTED name, not the stored one. V3.R51
+  // silently renames a colliding worktree_name ("overnight" → "overnight-2"), and
+  // the CLI keeps sending the real directory name, which is never renamed — so
+  // keying on the stored name compared "overnight" against "overnight-2", read
+  // them as different trees, and let a SECOND claim into the SAME tree. One tree,
+  // one branch, two active claims: exactly the commingled ship this guard exists
+  // to stop. See core_221 for the three-step repro.
+  //
+  // requested_worktree_name is NULL on rows written before core_221's backfill
+  // ran, so fall back to worktree_name — which for any row disambiguation never
+  // touched IS the requested name, and is the honest best answer for the rest. A
+  // deploy applies code and migration at different instants; this fallback is
+  // what keeps the guard correct in that window rather than reading every old
+  // row as worktree-less.
+  const treeOf = (c) => db.foldWorktreeName(
+    c.requested_worktree_name ?? c.worktree_name ?? null
+  );
+  const sameWorkingTree = (claim) => treeOf(claim) === incomingTree;
   // Defence in depth: only count claims that belong to THIS session, are genuinely
   // session-bound (a NULL-session row must never trip the block), AND would land in
   // the SAME working tree as the incoming claim.
   const inFlight = claims.find(
     (c) => c && c.creator_session_id != null && c.creator_session_id === creatorSessionId
-             && sameWorkingTree(c.worktree_name ?? null)
+             && sameWorkingTree(c)
   );
   if (inFlight) {
     return {

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.253",
+  "version": "1.19.254",
   "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/scripts/gds/run-unit-tests.js

@@ -73,7 +73,14 @@ const INTEGRATION = new Set([
   // platform-server — network + package build + a spawned server, run by its own
   // .github/workflows/consumer-layout-boot.yml, not this DB-free gate (task 2142).
   'consumer_layout_boot',
-  'claim_gate_open_blocker', 'claim_gate_rebase', 'clawback_confirmed_backlog',
+  'claim_gate_open_blocker', 'claim_gate_rebase',
+  // task 1002709: core_221's re-keyed backstop index against a real Postgres.
+  // The DB-free sibling pins the guard and the migration's text; this proves the
+  // 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.
+  'claims_requested_worktree_db',
+  'clawback_confirmed_backlog',
   // task 1003113: the copy_desk_flags schema half. The module's own tests are
   // DB-free and cover the pure layer; the rules that MATTER here live in the
   // schema — a CHECK-constraint reason floor whose whole argument is that no

package/src/module-api.js

@@ -933,8 +933,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.251 with no explicit bump. run 32205191350. (task 1002620)
 //   1.19.253 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.252 with no explicit bump. run 32205833181. (task 1002620)
+//   1.19.254 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.253 with no explicit bump. run 32207504942. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.253'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.254'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/claims_requested_worktree_db.mjs

@@ -0,0 +1,196 @@
+// tests/claims_requested_worktree_db.mjs — core_221's re-keyed backstop index
+// against a REAL Postgres (task 1002709).
+//
+// WHY THIS EXISTS BESIDE tests/one_active_claim_per_session.mjs. That file is
+// DB-free and covers the app GUARD plus text tripwires on the migration's shape.
+// It cannot cover the half that is a claim about the database: whether the
+// re-keyed unique index actually refuses the commingling INSERT, whether it
+// still ALLOWS the legitimate parallel-worktree case, and whether the migration
+// survives being applied over the very row shape the bug produced.
+//
+// The guard and the index are defence in depth for the same rule, and this
+// family of bugs (1002570, 1002589, 1002522, and now 1002709) has been almost
+// entirely about the two disagreeing. So both halves get their own proof.
+//
+// It SELF-SKIPS (exit 0) with no reachable Postgres, and is listed in
+// run-unit-tests.js's INTEGRATION set so the DB-free lane never runs it.
+//
+// Run:  DATABASE_URL=postgres://... node tests/claims_requested_worktree_db.mjs
+//
+// It builds its own throwaway `claims` table when one is absent, and truncates
+// only that table — so point it at a scratch database, never a real one.
+
+import pg from 'pg';
+import fs from 'node:fs';
+import path from 'node:path';
+import url from 'node:url';
+import { strict as assert } from 'node:assert';
+
+const pool = new pg.Pool({ connectionString: process.env.DATABASE_URL || undefined });
+
+try {
+  await pool.query('SELECT 1');
+} catch (e) {
+  console.log(`claims_requested_worktree_db.mjs SKIPPED — no reachable Postgres (${e.code || e.message}). Set DATABASE_URL to run.`);
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+
+// This test TRUNCATEs `claims`. Refuse to run against anything that looks like a
+// real database — a scratch container is the only sane target, and an accidental
+// DATABASE_URL pointing at prod would otherwise wipe the claims ledger.
+const { rows: realRows } = await pool.query(
+  `SELECT to_regclass('public.builders') IS NOT NULL AS has_builders`);
+if (realRows[0].has_builders) {
+  console.log('claims_requested_worktree_db.mjs SKIPPED — this database has a `builders` table, so it is not a scratch DB. It TRUNCATEs `claims`; point it at a throwaway Postgres.');
+  await pool.end().catch(() => {});
+  process.exit(0);
+}
+let passed = 0, failed = 0;
+async function t(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL ${name}\n     ${e.message}`); }
+}
+
+await pool.query(`
+  CREATE TABLE IF NOT EXISTS schema_migrations (version text PRIMARY KEY);
+  CREATE TABLE IF NOT EXISTS claims (
+    id bigserial PRIMARY KEY,
+    task_id bigint, builder_id bigint,
+    worktree_name text,
+    creator_session_id text,
+    claimed_at timestamptz DEFAULT now(),
+    released_at timestamptz,
+    outcome text);
+  CREATE UNIQUE INDEX IF NOT EXISTS uniq_active_claim_per_session_worktree
+    ON claims (creator_session_id, (COALESCE(worktree_name, '')))
+    WHERE released_at IS NULL AND creator_session_id IS NOT NULL;
+`);
+
+// Seed the PRE-migration commingled state: one session, one real tree, two
+// active claims that were only ever distinguished by the suffix. This is the row
+// shape the bug produced, and the migration has to heal it before it can build
+// the unique index.
+await pool.query(`TRUNCATE claims`);
+await pool.query(`INSERT INTO claims (task_id, builder_id, worktree_name, creator_session_id, claimed_at) VALUES
+  (1, 1, 'overnight',   'sess-A', now() - interval '2 hour'),
+  (2, 1, 'overnight-2', 'sess-A', now() - interval '1 hour')`);
+
+const HERE = path.dirname(url.fileURLToPath(import.meta.url));
+const MIG = fs.readFileSync(
+  path.join(HERE, '..', 'migrations', 'core_221_claims_requested_worktree_name.sql'), 'utf8');
+
+console.log('core_221 against real Postgres');
+
+await t('the migration applies over the commingled state (heals, then indexes)', async () => {
+  await pool.query(MIG);
+});
+
+await t('it deliberately UNDER-heals a pre-existing commingled pair, and does not guess', async () => {
+  // The honest limitation, asserted rather than hoped for. After the backfill,
+  // a commingled pair (stored "overnight" + "overnight-2", ONE real tree) and a
+  // legitimate pair (stored "foo" + "foo-2", TWO real trees) are
+  // INDISTINGUISHABLE — the requested name was never recorded, which is the
+  // whole bug. Suffix-stripping could close the first but would also silently
+  // kill the second, so the migration closes neither.
+  const { rows } = await pool.query(
+    `SELECT task_id, released_at FROM claims ORDER BY claimed_at`);
+  assert.equal(rows.length, 2);
+  assert.equal(rows[0].released_at, null);
+  assert.equal(rows[1].released_at, null,
+    'both stay active: a migration must not close a builder\'s live claim on a guess');
+});
+
+await t('but it DOES heal a genuine collision on the requested name', async () => {
+  // Rows written by the new code carry a real requested name, and two of those
+  // CAN collide — that is the case the heal exists for, and the case that would
+  // otherwise block CREATE UNIQUE INDEX on deploy.
+  await pool.query(`TRUNCATE claims`);
+  // Drop the index FIRST — the point is to recreate the pre-migration state in
+  // which these two rows can coexist, then prove the migration heals them.
+  await pool.query('DROP INDEX IF EXISTS uniq_active_claim_per_session_requested_worktree');
+  await pool.query(`INSERT INTO claims (task_id, builder_id, worktree_name, requested_worktree_name, creator_session_id, claimed_at) VALUES
+    (60, 1, 'wt',   'wt', 'sess-H', now() - interval '2 hour'),
+    (61, 1, 'wt-2', 'wt', 'sess-H', now() - interval '1 hour')`);
+  await pool.query(MIG);
+  const { rows } = await pool.query(
+    `SELECT task_id, released_at, outcome FROM claims ORDER BY claimed_at`);
+  assert.equal(rows[0].released_at, null, 'the earliest survives');
+  assert.ok(rows[1].released_at, 'the later is closed');
+  assert.equal(rows[1].outcome, 'abandoned');
+});
+
+await t('the backfill copies worktree_name across, and never overwrites a real value', async () => {
+  await pool.query(`TRUNCATE claims`);
+  await pool.query(`INSERT INTO claims (task_id, builder_id, worktree_name, requested_worktree_name, creator_session_id) VALUES
+    (70, 1, 'legacy', NULL,      'sess-I'),
+    (71, 1, 'newer',  'asked-for','sess-J')`);
+  await pool.query(MIG);
+  const { rows } = await pool.query(
+    `SELECT task_id, worktree_name, requested_worktree_name FROM claims ORDER BY task_id`);
+  assert.equal(rows[0].requested_worktree_name, 'legacy', 'a NULL historical row is filled from the stored name');
+  assert.equal(rows[1].requested_worktree_name, 'asked-for',
+    'a row that already carries a real requested name is left alone — the guard on the UPDATE');
+});
+
+await t('re-running the migration is idempotent', async () => {
+  await pool.query(MIG);
+});
+
+await t('the old index is gone and the new one exists', async () => {
+  const { rows } = await pool.query(
+    `SELECT indexname FROM pg_indexes WHERE tablename = 'claims'`);
+  const names = rows.map((r) => r.indexname);
+  assert.ok(!names.includes('uniq_active_claim_per_session_worktree'),
+    'leaving it would re-refuse the legitimate foo / foo-2 case');
+  assert.ok(names.includes('uniq_active_claim_per_session_requested_worktree'));
+});
+
+await pool.query(`TRUNCATE claims`);
+const ins = (o) => pool.query(
+  `INSERT INTO claims (task_id, builder_id, worktree_name, requested_worktree_name, creator_session_id)
+   VALUES ($1,1,$2,$3,$4) RETURNING id`,
+  [o.task, o.stored, o.requested, o.session]);
+
+console.log('\nthe index now catches what the guard catches');
+
+await t('THE HOLE IS CLOSED: same session, same REQUESTED tree, second claim → 23505', async () => {
+  await ins({ task: 10, stored: 'overnight-2', requested: 'overnight', session: 'sess-B' });
+  await assert.rejects(
+    () => ins({ task: 11, stored: 'overnight-3', requested: 'overnight', session: 'sess-B' }),
+    (e) => e.code === '23505' && e.constraint === 'uniq_active_claim_per_session_requested_worktree');
+});
+
+await t('two genuinely different trees in one session still BOTH insert', async () => {
+  await pool.query(`TRUNCATE claims`);
+  await ins({ task: 20, stored: 'foo', requested: 'foo', session: 'sess-C' });
+  const r = await ins({ task: 21, stored: 'foo-2', requested: 'foo-2', session: 'sess-C' });
+  assert.ok(r.rows[0].id, 'the parallel-worktree workflow must keep working');
+});
+
+await t('two worktree-less claims in one session still self-collide', async () => {
+  await pool.query(`TRUNCATE claims`);
+  await ins({ task: 30, stored: null, requested: null, session: 'sess-D' });
+  await assert.rejects(
+    () => ins({ task: 31, stored: null, requested: null, session: 'sess-D' }),
+    (e) => e.code === '23505', 'one shared clone, one branch — NULLs must fold via COALESCE');
+});
+
+await t('a released claim frees the name for reuse (the overnight builder)', async () => {
+  await pool.query(`TRUNCATE claims`);
+  await ins({ task: 40, stored: 'overnight', requested: 'overnight', session: 'sess-E' });
+  await pool.query(`UPDATE claims SET released_at = now() WHERE task_id = 40`);
+  const r = await ins({ task: 41, stored: 'overnight', requested: 'overnight', session: 'sess-E' });
+  assert.ok(r.rows[0].id, 'sequential reuse is load-bearing for the overnight builder');
+});
+
+await t('unbound (NULL-session) claims are still exempt', async () => {
+  await pool.query(`TRUNCATE claims`);
+  await ins({ task: 50, stored: 'shared', requested: 'shared', session: null });
+  const r = await ins({ task: 51, stored: 'shared', requested: 'shared', session: null });
+  assert.ok(r.rows[0].id, 'web/unbound claims may coexist — the partial predicate excludes them');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+await pool.end();
+process.exit(failed ? 1 : 0);

package/tests/one_active_claim_per_session.mjs

@@ -337,5 +337,130 @@ t('core_204 keeps the 180 predicate (active + bound rows only) and heals first',
     'the pre-CREATE heal must group by the NEW key');
 });
 
+// =========================================================================
+// task 1002709 — the disambiguation hole. V3.R51 silently RENAMES a colliding
+// worktree_name ("overnight" -> "overnight-2") while the CLI keeps sending the
+// real directory name, which is never renamed. Keying the guard on the STORED
+// name therefore compared two different strings for ONE tree and let a second
+// claim through: one tree, one branch, two active claims — the commingled ship
+// this guard exists to stop. The fix stores the REQUESTED name too and keys on
+// that (core_221).
+// =========================================================================
+
+t('THE REPRO: a second claim from the same session into a RENAMED tree is refused', () => {
+  // Step 1-2 already happened: this session's first claim asked for "overnight",
+  // collided with another builder's active "overnight", and was STORED as
+  // "overnight-2". Step 3 is this call — same session, same real directory.
+  const held = {
+    claim_id: 90, task_id: 800, creator_session_id: 'sess-9',
+    worktree_name: 'overnight-2',            // what disambiguation stored
+    requested_worktree_name: 'overnight',    // what the caller actually asked for
+    title: 'First',
+  };
+  const out = shouldRefuseSessionClaim({
+    activeClaimsForSession: [held],
+    creatorSessionId: 'sess-9',
+    worktreeName: 'overnight',               // the CLI still sends the real dir
+  });
+  assert.equal(out.refuse, true,
+    'before task 1002709 this ALLOWED — "overnight" vs the stored "overnight-2" read as two trees');
+  assert.equal(out.reason, 'session_already_has_active_claim');
+  assert.equal(out.inFlightTaskId, 800);
+});
+
+t('a builder genuinely running "foo" and "foo-2" side by side is still allowed', () => {
+  // The false-refusal this whole family of bugs is about. Matching
+  // /^<requested>-\d+$/ in the guard would have broken exactly this, which is
+  // why the requested name is STORED rather than pattern-matched.
+  const held = {
+    claim_id: 91, task_id: 801, creator_session_id: 'sess-9',
+    worktree_name: 'foo', requested_worktree_name: 'foo', title: 'In foo',
+  };
+  const out = shouldRefuseSessionClaim({
+    activeClaimsForSession: [held],
+    creatorSessionId: 'sess-9',
+    worktreeName: 'foo-2',
+  });
+  assert.equal(out.refuse, false, 'two real, separate trees — two branches, no commingling');
+});
+
+t('rows written before the backfill fall back to worktree_name', () => {
+  // A deploy applies code and migration at different instants. In that window an
+  // active row has requested_worktree_name NULL, and for any row disambiguation
+  // never touched the stored name IS the requested one — so the fallback keeps
+  // the guard correct instead of reading every old row as worktree-less.
+  const legacy = {
+    claim_id: 92, task_id: 802, creator_session_id: 'sess-9',
+    worktree_name: 'legacy-tree', title: 'Legacy',
+    // requested_worktree_name deliberately absent
+  };
+  assert.equal(shouldRefuseSessionClaim({
+    activeClaimsForSession: [legacy], creatorSessionId: 'sess-9', worktreeName: 'legacy-tree',
+  }).refuse, true, 'same tree by the fallback → refuse');
+  assert.equal(shouldRefuseSessionClaim({
+    activeClaimsForSession: [legacy], creatorSessionId: 'sess-9', worktreeName: 'other-tree',
+  }).refuse, false, 'different tree → still allowed');
+});
+
+t('an explicit NULL requested name does NOT silently become the stored name', () => {
+  // `??` and not `||`: a row whose requested name is genuinely null (a
+  // worktree-less claim, backfilled) must fold to the shared-clone group, and a
+  // row whose stored name is null must not resurrect anything either.
+  const worktreeless = {
+    claim_id: 93, task_id: 803, creator_session_id: 'sess-9',
+    worktree_name: null, requested_worktree_name: null, title: 'Shared clone',
+  };
+  assert.equal(shouldRefuseSessionClaim({
+    activeClaimsForSession: [worktreeless], creatorSessionId: 'sess-9', worktreeName: null,
+  }).refuse, true, 'one shared clone, one branch — genuinely commingles');
+  assert.equal(shouldRefuseSessionClaim({
+    activeClaimsForSession: [worktreeless], creatorSessionId: 'sess-9', worktreeName: 'wt-real',
+  }).refuse, false);
+});
+
+const mig221 = () => readFileSync(
+  join(dirname(fileURLToPath(import.meta.url)),
+    '../migrations/core_221_claims_requested_worktree_name.sql'),
+  'utf8');
+
+t('core_221 adds the column additively and backfills without overwriting', () => {
+  assert.match(mig221(), /ADD COLUMN IF NOT EXISTS requested_worktree_name text/i);
+  assert.match(mig221(), /WHERE requested_worktree_name IS NULL/i,
+    'the backfill must be guarded so a re-run cannot overwrite a real value');
+});
+
+t('core_221 re-keys the index onto the REQUESTED name, and drops the old one', () => {
+  assert.match(mig221(), /DROP INDEX IF EXISTS uniq_active_claim_per_session_worktree\b/,
+    'leaving core_204 index alongside would re-refuse the legitimate foo / foo-2 case');
+  assert.match(mig221(), /CREATE UNIQUE INDEX IF NOT EXISTS uniq_active_claim_per_session_requested_worktree/);
+  assert.match(mig221(), /COALESCE\(requested_worktree_name,\s*''\)/i,
+    'NULLs are DISTINCT in a plain unique index — the fold is what makes a shared clone self-collide');
+});
+
+t('core_221 keeps the partial predicate and heals on the NEW key first', () => {
+  assert.match(mig221(), /WHERE released_at IS NULL AND creator_session_id IS NOT NULL/,
+    'web/unbound claims stay excluded, as in 180 and core_204');
+  assert.match(mig221(), /PARTITION BY c\.creator_session_id,\s*COALESCE\(c\.requested_worktree_name,\s*''\)/i,
+    'a unique index refuses to create over violating rows — re-keying can newly collide exactly where this bug lived');
+});
+
+t('all three index generations stay recognised by claimUniqueViolationError', () => {
+  // An unrecognised constraint falls closed onto the generic ALREADY_CLAIMED,
+  // which for this case is the phantom-rival answer task 1002589 removed.
+  for (const name of [
+    'uniq_active_claim_per_session',
+    'uniq_active_claim_per_session_worktree',
+    'uniq_active_claim_per_session_requested_worktree',
+  ]) {
+    assert.equal(
+      claimUniqueViolationError({ constraint: name }).code,
+      'session_already_has_bound_claim',
+      `${name} must render as the honest session answer`,
+    );
+  }
+  assert.equal(claimUniqueViolationError({ constraint: 'uniq_active_claim_per_task' }).code,
+    'ALREADY_CLAIMED', 'a genuine per-task race still reads as a rival claim');
+});
+
 console.log(`\n${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);