@bongos/core 1.19.252 → 1.19.254

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.252",
+  "version": "1.19.254",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.252",
+      "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.252",
+  "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

@@ -931,8 +931,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.250 with no explicit bump. run 32204008770. (task 1002620)
 //   1.19.252 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         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.252'; // 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/government_charter_library.mjs

@@ -67,7 +67,12 @@ test('the library presents all seven structures with honest selectable marks (cl
   assert.equal(selectableTrue, 4, 'monarchy, timocratic republic, direct democracy, foundation — the config-expressible four');
   const trueBlocks = lib.split('selectable: true').slice(1);
   for (const b of trueBlocks) {
-    assert.ok(b.slice(0, 200).includes('how:'), 'a selectable structure names its configuration');
+    // Window widened from 200 (task 1003095): a selectable entry now also carries
+    // `predicate` + `seatsRanks` ahead of `how`, which the test below checks
+    // against the real parser. Cut to the next entry rather than a magic length,
+    // so adding another field cannot silently push `how` out of view again.
+    const entry = b.split('{ key:')[0];
+    assert.ok(entry.includes('how:'), 'a selectable structure names its configuration');
   }
   assert.match(client, /recommended at your headcount/, 'the one live datum is rendered');
   assert.match(client, /c\.key === recommendedKey/, "the pill is driven by the SERVER's recommendation, never re-derived client-side");
@@ -75,3 +80,104 @@ test('the library presents all seven structures with honest selectable marks (cl
     assert.ok(client.includes(`name: '${t}'`), `trajectory ${t} present`);
   }
 });
+
+
+// ── R26's ask, made mechanical (task 1003095) ───────────────────────────────
+//
+// The library is the ONLY place in the product that tells an owner WHAT TO TYPE.
+// That makes a wrong `how` line worse than no library: an owner who followed
+// `membership rank:xenos (everyone)` under the old exact-match grammar handed
+// the board to newcomers and locked themselves out. R26's done-when asks for
+// "selectable-today is honestly marked" — prose cannot be honest by assertion,
+// so this checks every selectable charter's predicate against the REAL parser.
+//
+// Deliberately NOT a copy of the intent: it imports
+// modules/government/membership-predicate.js, the same module the resolver and
+// the config sanitizer use. If the grammar moves underneath this page again,
+// this test reds instead of the page quietly lying.
+
+function charterEntries() {
+  const client = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/government.js'), 'utf8');
+  const lib = client.slice(client.indexOf('const CHARTERS'), client.indexOf('const TRAJECTORIES'));
+  const out = [];
+  for (const block of lib.split('{ key:').slice(1)) {
+    const key = /^\s*'([a-z-]+)'/.exec(block);
+    if (!key) continue;
+    const selectable = /selectable: (true|false)/.exec(block);
+    const predicate = /predicate: (?:'([^']*)'|null)/.exec(block);
+    const seats = /seatsRanks: (?:\[([^\]]*)\]|null)/.exec(block);
+    const how = /how: '([^']*)'/.exec(block) || /how: "([^"]*)"/.exec(block);
+    out.push({
+      key: key[1],
+      selectable: selectable ? selectable[1] === 'true' : null,
+      predicate: predicate ? (predicate[1] ?? null) : undefined,
+      seatsRanks: seats ? (seats[1] ? seats[1].split(',').map((x) => x.trim().replace(/'/g, '')) : null) : undefined,
+      how: how ? how[1] : null,
+    });
+  }
+  return out;
+}
+
+test('every SELECTABLE charter names a predicate the real resolver would actually seat as described', () => {
+  const { parseMembershipPredicate } = require(path.join(GOV, 'membership-predicate.js'));
+  const entries = charterEntries();
+  assert.equal(entries.length, 7, 'sanity: parsed all seven structures');
+
+  for (const c of entries.filter((e) => e.selectable)) {
+    assert.notEqual(c.predicate, undefined, `${c.key}: a selectable charter must declare a predicate field (null = owner-chosen)`);
+    assert.notEqual(c.seatsRanks, undefined, `${c.key}: a selectable charter must declare seatsRanks`);
+
+    if (c.predicate === null) {
+      // Owner-chosen (Foundation's custom trustee rank). Honest rather than
+      // unchecked: it must SAY the predicate is theirs to name.
+      assert.equal(c.seatsRanks, null, `${c.key}: an owner-chosen predicate cannot claim a fixed seat list`);
+      assert.match(c.how, /custom/i, `${c.key}: must say the rank is one the owner creates`);
+      continue;
+    }
+
+    const parsed = parseMembershipPredicate(c.predicate);
+    assert.ok(parsed, `${c.key}: "${c.predicate}" does not parse — this page would tell an owner to type something that seats NOBODY`);
+    assert.deepEqual([...parsed.rankKeys], c.seatsRanks,
+      `${c.key}: "${c.predicate}" seats ${JSON.stringify([...parsed.rankKeys])}, but the library claims ${JSON.stringify(c.seatsRanks)}`);
+    assert.ok(c.how.includes(c.predicate),
+      `${c.key}: the how-line must contain the exact predicate an owner types (expected "${c.predicate}" in "${c.how}")`);
+  }
+});
+
+test('THE REGRESSION: the two lines that were untrue now seat what they say', () => {
+  const { parseMembershipPredicate } = require(path.join(GOV, 'membership-predicate.js'));
+  const by = Object.fromEntries(charterEntries().map((c) => [c.key, c]));
+
+  // Direct Democracy said "rank:xenos (everyone)" and seated NEWCOMERS ONLY.
+  const dd = by['direct-democracy'];
+  assert.equal(dd.predicate, 'rank:xenos+');
+  assert.deepEqual([...parseMembershipPredicate(dd.predicate).rankKeys], ['xenos', 'thetes', 'metic', 'archon'],
+    'every builder, which is what "everyone" has to mean');
+  assert.ok(!/rank:xenos[^+]/.test(dd.how), 'the how-line must not show the bare form that caused the bug');
+
+  // Timocratic Republic was true as far as it went and silent about Archons.
+  const tr = by['timocratic-republic'];
+  assert.equal(tr.predicate, 'rank:metic+');
+  assert.deepEqual([...parseMembershipPredicate(tr.predicate).rankKeys], ['metic', 'archon']);
+  assert.match(tr.how, /Archons included/i, 'the omission that made it quietly surprising is now stated');
+});
+
+test('the recommendation names a charter the config can actually express', () => {
+  // The library recommended "a consent circle of all trusted members" at
+  // headcount 3–8 — a phrase with no predicate behind it under exact-match. The
+  // recommendation must point at a charter this page can tell an owner to type.
+  const by = Object.fromEntries(charterEntries().map((c) => [c.key, c]));
+  for (const n of [1, 3, 8, 9, 50, 150]) {
+    const rec = recommendedCharter(n);
+    const charter = by[rec.key];
+    assert.ok(charter, `headcount ${n} recommends "${rec.key}", which is not in the library`);
+    if (charter.selectable) {
+      assert.ok(charter.predicate !== undefined,
+        `headcount ${n} recommends selectable "${rec.key}" — it must carry a checkable predicate`);
+    }
+  }
+  const circle = recommendedCharter(3);
+  assert.equal(circle.key, 'direct-democracy');
+  assert.match(circle.why, /rank:xenos\+/,
+    'the why must name the predicate that delivers it, not a phrase with nothing behind it');
+});

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);