@bongos/core 1.19.63 → 1.19.64

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.63",
-  "core_contract": "1.19.63",
-  "source_commit": "aecb337d2bcfb665111227e9aebaffa93f867699",
+  "core_version": "1.19.64",
+  "core_contract": "1.19.64",
+  "source_commit": "ce3ba6421d4c20ca1f0b218a1b09d8825db932b1",
   "source_ref": "HEAD",
-  "built_at": "2026-08-12T01:29:46.616Z",
+  "built_at": "2026-08-12T03:26:56.981Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 291,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1532,
-  "tree_sha256": "165231bc8a6ec61199f57070fc8267562e283cff9b5804d340d4f3b57cc98de2",
+  "tree_sha256": "c8e496c8bd2e61bc44e0ccb85fcceadb92acbeaa5ac0c7db1f856004a36f2728",
   "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": "9613664f0f3906aeda7c384c3a6dfaacb8a0a048b0010da8a011831846d7911e"
+      "sha256": "3aa1e9074bd62168f999139533d672b0e0369186e2a78bbc966bca940df8d012"
     },
     {
       "path": "docs/adr/0097-retroactive-reward-backfill.md",
@@ -3382,7 +3382,7 @@
     {
       "path": "modules/lifecycle/db.js",
       "mode": "0000644",
-      "sha256": "37303ffa7a795ea41db83f346bc736898720a3d1521434f566a71bbeb7b4dc15"
+      "sha256": "bc1526d068698e489fc2a698c04418e60097f18b56fd5c0dcdb6a6f62bbd1c81"
     },
     {
       "path": "modules/lifecycle/done-when.js",
@@ -3457,7 +3457,7 @@
     {
       "path": "modules/lifecycle/routes/claims.js",
       "mode": "0000644",
-      "sha256": "92065e0a5cfd2a5d76bbf04f4efafe0e2b3bc31cf616136963d4c07fad25047e"
+      "sha256": "60f698b88fab3b850e2ab7d4350b7192ca57fa932089d0a24a187add08e5c819"
     },
     {
       "path": "modules/lifecycle/routes/dependencies.js",
@@ -4037,12 +4037,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ec06847fa5cf675d4847afeed5612e44a0fd336694a1187d342a9f60ef957b09"
+      "sha256": "90fef156fcc7117e3a88064eaab10da019b48fc2b1b5586cbbfe7d4006333682"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "612d7a22ac1c386d80c1c99b9aa52d70363c8a7a4f8ffb0598624c995578f060"
+      "sha256": "9fd4475c4f673be84d4504811890f5ec5339a226e4c738d41b6bb94c808cc76e"
     },
     {
       "path": "public-docs/index.html",
@@ -5662,7 +5662,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "dfd274bc93670afa2368e0abea4d79ab5bd415996ed11c56a14cbafb449aafc6"
+      "sha256": "d55be57d6e2c4435e3b1cdab9543b90c449358b26ba1035fdb82b097f41ca7d6"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -7052,7 +7052,7 @@
     {
       "path": "tests/one_active_claim_per_session.mjs",
       "mode": "0000644",
-      "sha256": "3a4d6cc704d0ecd7be2f094ad10baf9c725a2045587994f076de76fb26ce90e5"
+      "sha256": "030c7f3958d1fef45977326b52596e21638fe80b4ff9e7ecba31c76063283aea"
     },
     {
       "path": "tests/orphaned_claim_ship.mjs",

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

@@ -40,6 +40,10 @@ The default claim flow (`.claude/skills/builder-claim/SKILL.md`) ensures the tas
 
 > **Amended 2026-08-06 (task 1002570 / `core_204`).** The index as shipped was *stricter* than the worktree-scoped guard above: keyed on `creator_session_id` alone, it refused at the DB layer the second-worktree parallel claim the guard deliberately allows — breaking the many-sessions-per-builder norm this ADR set out to preserve. `migrations/<redacted>.sql` re-keys it to `(creator_session_id, COALESCE(worktree_name, ''))` under the name `uniq_active_claim_per_session_worktree`, same partial predicate, so the backstop now enforces exactly the guard's boundary. The `COALESCE` fold (rather than PG15's `NULLS NOT DISTINCT`) is load-bearing: a plain composite index treats NULLs as distinct, so two worktree-less claims off one shared clone would both insert and re-open the commingling hole. A `23505` from either index generation surfaces as `session_already_has_bound_claim` (task 1002589), never the false `ALREADY_CLAIMED`.
 
+> **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.
+
 ## Consequences
 
 - A session can hold at most one active claim — commingled ships are structurally prevented, not just discouraged.

package/modules/lifecycle/db.js

@@ -335,6 +335,30 @@ function singleRungPromotionError(oldRank, newRank) {
   };
 }
 
+// foldWorktreeName — task 1002522. The ONE normalization of an incoming
+// worktree_name, applied at every ingest point so the app guard
+// (shouldRefuseSessionClaim) and its DB backstop (core_204's index, keyed on
+// (creator_session_id, COALESCE(worktree_name, ''))) can never disagree about
+// which claims share a working tree.
+//
+// The index folds NULL to '' — so to Postgres an EMPTY-string name IS the
+// worktree-less group. The guard compared raw values, where '' !== null: it
+// waved through a ''-named claim beside a worktree-less one, and the INSERT
+// then failed the backstop with a 23505 the caller never earned. Whitespace-only
+// is the same case wearing a coat (`.claude/worktrees/<blank>` is the repo root,
+// not a tree), so it folds too, and surrounding whitespace is trimmed rather
+// than stored — an untrimmed name would key the index differently from the
+// trimmed one the guard compared.
+//
+// Fold ONCE, at ingest: claimTask/claimTasksBatch normalize before the INSERT,
+// so every stored name is already trimmed-or-NULL and the guard's comparison of
+// stored rows is exact. Pure + exported for DB-free tests.
+function foldWorktreeName(name) {
+  if (name == null) return null;
+  const trimmed = String(name).trim();
+  return trimmed === '' ? null : trimmed;
+}
+
 // disambiguateWorktreeName — V3.R51 (#270). Two simultaneously-ACTIVE claims
 // must never share a worktree_name: `.claude/worktrees/<name>` is a filesystem
 // path, and two live builders pointing at the same one would stomp each other.
@@ -2762,7 +2786,10 @@ async function claimTask({ taskId, builderId, worktreeName, headSha, creatorSess
     // 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.
-    let finalWorktreeName = worktreeName ?? null;
+    // 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);
     if (finalWorktreeName) {
       const { rows: activeNameRows } = await client.query(
         `SELECT worktree_name FROM claims
@@ -3121,8 +3148,12 @@ async function claimTasksBatch({ taskIds, builderId, worktreePrefix, creatorSess
         );
         reservedMigrationNumber = bumpRows[0].allocated;
       }
-      const worktreeName = worktreePrefix
-        ? `${worktreePrefix}-${t.id}`
+      // 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 {
@@ -5546,6 +5577,7 @@ module.exports = {
   countShippedTasksForBuilder,
   singleRungPromotionError,
   disambiguateWorktreeName,
+  foldWorktreeName,
   updateTaskParallelSafe,
   updateTaskSecuritySensitive,
   updateTaskAutomationTag,

package/modules/lifecycle/routes/claims.js

@@ -80,13 +80,17 @@ function shouldRefuseSessionClaim({ activeClaimsForSession, creatorSessionId, wo
     return { refuse: false, inFlightTaskId: null, inFlightTitle: null, reason: null };
   }
   const claims = Array.isArray(activeClaimsForSession) ? activeClaimsForSession : [];
-  const incomingTree = worktreeName == null ? null : worktreeName;
-  // Two claims share a WORKING TREE iff their worktree_names match, or both are
-  // null (a worktree-less clone — the single branch genuinely commingles).
-  const sameWorkingTree = (name) => {
-    const t = name == null ? null : name;
-    return t === incomingTree;
-  };
+  // task 1002522: fold through db.foldWorktreeName — the SAME normalization the
+  // INSERT applies — so this decision keys trees exactly the way core_204's
+  // backstop index does (it folds NULL and '' into one group via
+  // COALESCE(worktree_name, '')). Comparing raw values let a ''-named claim slip
+  // past the guard and then trip the index, refusing a claim on a task that was
+  // never taken.
+  const incomingTree = db.foldWorktreeName(worktreeName);
+  // 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;
   // 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.
@@ -122,7 +126,9 @@ async function gateOneActiveClaimPerSession(req, res, next) {
   // The incoming claim's working tree — the hazard boundary the guard keys on. A
   // second claim in a DIFFERENT worktree is safe (different branch); only a second
   // claim into the SAME tree (or off one worktree-less clone) commingles.
-  const worktreeName = req.body?.worktree_name ?? null;
+  // Folded (task 1002522) so the guard, the refusal message, and the row the
+  // INSERT will actually write all speak about the same tree.
+  const worktreeName = db.foldWorktreeName(req.body?.worktree_name);
   let activeClaimsForSession;
   try {
     activeClaimsForSession = await db.getActiveClaimsForSession(creatorSessionId);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.63",
+  "version": "1.19.64",
   "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/src/module-api.js

@@ -553,8 +553,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.61 with no explicit bump. run 31552833331. (task 1002620)
 //   1.19.63 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.62 with no explicit bump. run 31553743979. (task 1002620)
+//   1.19.64 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.63 with no explicit bump. run 31560059785. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.63'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.64'; // 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/one_active_claim_per_session.mjs

@@ -183,6 +183,80 @@ t('names the in-flight task in the MATCHING worktree, not the first row', () =>
   assert.equal(d.inFlightTitle, 'Two');
 });
 
+// =========================================================================
+// task 1002522 — the guard and core_204's backstop index must agree EXACTLY on
+// which claims share a tree. The index keys (creator_session_id,
+// COALESCE(worktree_name, '')), so to Postgres '' IS the worktree-less group;
+// the guard compared raw values, where '' !== null. db.foldWorktreeName is the
+// single normalization both sides now use (and claimTask applies before the
+// INSERT, so stored rows are already trimmed-or-NULL).
+// =========================================================================
+const { foldWorktreeName } = require('../modules/lifecycle/db.js');
+
+t('foldWorktreeName folds null / empty / whitespace to the same NULL key', () => {
+  assert.equal(foldWorktreeName(null), null);
+  assert.equal(foldWorktreeName(undefined), null);
+  assert.equal(foldWorktreeName(''), null);
+  assert.equal(foldWorktreeName('   '), null);
+  assert.equal(foldWorktreeName('\t\n'), null);
+});
+
+t('foldWorktreeName trims but never renames a real worktree', () => {
+  assert.equal(foldWorktreeName('wt-a'), 'wt-a');
+  assert.equal(foldWorktreeName('  wt-a  '), 'wt-a');
+  // Distinct trees stay distinct — the fold must not collapse parallel work.
+  assert.notEqual(foldWorktreeName('wt-a'), foldWorktreeName('wt-a-2'));
+});
+
+t("empty-string worktree is the SAME tree as worktree-less → refused (matches the index)", () => {
+  // Before the fold this returned allow, and the INSERT then tripped
+  // uniq_active_claim_per_session_worktree — a 23505 on a task nobody had taken.
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: '',
+    activeClaimsForSession: [
+      { claim_id: 50, task_id: 70, creator_session_id: 'sess-6', worktree_name: null, title: 'shared clone' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 70);
+});
+
+t('the mirror case: worktree-less incoming vs a stored empty-string name → refused', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: null,
+    activeClaimsForSession: [
+      { claim_id: 51, task_id: 71, creator_session_id: 'sess-6', worktree_name: '   ', title: 'blank name' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 71);
+});
+
+t('whitespace around a real name does not fake a second tree', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: ' wt-a ',
+    activeClaimsForSession: [
+      { claim_id: 52, task_id: 72, creator_session_id: 'sess-6', worktree_name: 'wt-a', title: 'A' },
+    ],
+  });
+  assert.equal(d.refuse, true);
+  assert.equal(d.inFlightTaskId, 72);
+});
+
+t('the fold does NOT re-break parallel worktrees (the bug this family fixed)', () => {
+  const d = shouldRefuseSessionClaim({
+    creatorSessionId: 'sess-6',
+    worktreeName: 'wt-b',
+    activeClaimsForSession: [
+      { claim_id: 53, task_id: 73, creator_session_id: 'sess-6', worktree_name: 'wt-a', title: 'A' },
+    ],
+  });
+  assert.equal(d.refuse, false);
+});
+
 // =========================================================================
 // task 1002589 (idea 1000638) — the DB backstop's ERROR SURFACE. A claims
 // INSERT can trip TWO partial unique indexes; claimTask used to map every pg