@bongos/core 1.19.686 → 1.19.687

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.686",
-  "core_contract": "1.19.686",
-  "source_commit": "8f52ba91e493a99b11854b478933ac337d300c17",
+  "core_version": "1.19.687",
+  "core_contract": "1.19.687",
+  "source_commit": "80529e693e8b33d02d80143fce82b5300e5f0c01",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T21:51:30.504Z",
+  "built_at": "2026-09-12T23:13:15.800Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 477,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2626,
-  "tree_sha256": "fe7db21bbf1cad87c2f341633ce01284a5dec1940e45febe42bb66534e623865",
+  "tree_sha256": "c85f4828bf21b1e106dfef13e6d603ea2774214cacdaf87ddbdb7f4242506e5c",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "048ac25e9d49525c5bbf927234ff4b2386134bc83978ac2c6ba1fcd86764d3a3"
+      "sha256": "f596cd52ec02d7e08108da8ce76a21a085aa1455989496d6a8501d1d7955ec5a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -5872,7 +5872,7 @@
     {
       "path": "modules/lifecycle/routes/claims.js",
       "mode": "0000644",
-      "sha256": "8a4f6d5513b97e84c44695b88e42c6e5bdc1875e97202be41caf6c739b2fa42e"
+      "sha256": "9d4625ddaaa79e8496e05980153aca1a171d79aad3a32f1711be60be3be05955"
     },
     {
       "path": "modules/lifecycle/routes/closeness.js",
@@ -7782,12 +7782,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8280f5610873fad997cfc9c6508c7bcdb9b3fe38ea34ac55b31b6a8a46931ab7"
+      "sha256": "ad18930429a58c935061b8269dfea3c2fcbb1095eeff26859158679b9faf37d3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "47a7ca80b0914f25810d596d5bce2393d5e3ee93bb302a82a34047c76799720d"
+      "sha256": "f4d3a3c0536c755502e2f9bafaf07a54fda378a3394b22e0a3a3368992300073"
     },
     {
       "path": "public-docs/index.html",
@@ -9547,7 +9547,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "1da978ad0d4fe540320d997da64154fb2780d80c346d1888cf6789e85f1c455d"
+      "sha256": "c323740fa5182f9e2c200cdbd349d19753cf7d6f2faee9cf98ff44ba13249d2f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9702,7 +9702,7 @@
     {
       "path": "tests/api_path_404.mjs",
       "mode": "0000644",
-      "sha256": "427f5750b4115fc0ddd30f6f7f8202521d5b31300b191093bc98f8416bb4a228"
+      "sha256": "82ca3700f6dd9d0aa88b39a0d6c45a03c20628201508b619e36a6d77ce0215ce"
     },
     {
       "path": "tests/app_pair.mjs",

package/docs/module-api-changelog.md

@@ -1831,5 +1831,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.684 with no explicit bump. run 34719298791. (task 1002620)
   1.19.686 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.685 with no explicit bump. run 34721104118. (task 1002620)
+  1.19.687 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.686 with no explicit bump. run 34724811506. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/lifecycle/routes/claims.js

@@ -68,6 +68,28 @@ function taskNotReadyHint(taskId, currentStatus) {
     : `Task #${idNum} is '${currentStatus}', not 'ready' — only 'ready' tasks are claimable (promote applies to 'backlog': POST /api/bongos/tasks/${idNum}/promote).`;
 }
 
+// task 1003768: the way-forward hint on a REBASE_REQUIRED 409 (ADR 0120 part 3's
+// owed-rebase claim gate). Pure + exported so the wording is pinned by a test,
+// the same contract taskNotReadyHint above carries.
+//
+// WHY THE MENU CHANGED. The old wording offered "(rebase its branch + re-ship, or
+// /merge-mode)". /merge-mode cannot run on a builder machine with no GitHub push
+// credential — and that is the DOCUMENTED DEFAULT posture, not a misconfiguration
+// (ADR 0031 §6 / ADR 0055: landing is server-mediated, /builder-ship uploads a
+// bundle and the SERVER pushes). Meanwhile /strand-fix — whose own frontmatter
+// says it is "the fix for a claim refused 409 REBASE_REQUIRED" — went unmentioned.
+// So the one exit that works everywhere was missing and the first one offered
+// fails on auth for most readers. The gate was always clearable; the MENU was
+// wrong, and this hint is the menu.
+//
+// Ordering is the fix: the universally-available command leads, /merge-mode is
+// marked as needing a push credential rather than dropped (it is still the right
+// tool on a credentialed machine), and /builder-release stays as the give-up exit.
+function rebaseRequiredHint(rebaseTasks) {
+  const ids = (rebaseTasks || []).map((t) => `task ${t.id}`);
+  return `Your queue is gated: ${ids.length} confirmed task(s) await your rebase (${ids.join(', ') || 'unknown'}). Clear it with /strand-fix N (works on any machine), or rebase the branch and re-ship — /merge-mode only if this machine has a GitHub push credential. To give up on one instead, /builder-release it. If CI is simply backed up, waiting is correct: a task already landed clears the gate on its own.`;
+}
+
 // task 1642 (+ the worktree-keying fix) — the pure one-active-claim decision.
 // Working two tasks from one WORKING TREE means every commit lands on the single
 // branch that tree owns; /builder-ship publishes the whole branch, so shipping one
@@ -343,8 +365,7 @@ module.exports = function buildClaimsRouter() {
         // ADR 0120 part 3: name the offending task(s) + the two ways to clear the
         // gate, so the builder isn't left guessing why their claim was refused.
         if (err.code === 'REBASE_REQUIRED') {
-          const ids = (err.rebaseTasks || []).map((t) => `task ${t.id}`);
-          err.hint = `Your queue is gated: ${ids.length} confirmed task(s) await your rebase (${ids.join(', ') || 'unknown'}). Land each (rebase its branch + re-ship, or /merge-mode) — or /builder-release it — then claim new work.`;
+          err.hint = rebaseRequiredHint(err.rebaseTasks);
         }
         // task 1002650: name the blocker(s) and the way forward — the same rule
         // the claimable feed enforces, spoken at the gate instead of a bare 409.
@@ -645,6 +666,10 @@ module.exports = function buildClaimsRouter() {
 module.exports.resolveCreatorSessionId = resolveCreatorSessionId;
 // V4.R14 (#952): the TASK_NOT_READY 409 hint — exported so its wording is pinned.
 module.exports.taskNotReadyHint = taskNotReadyHint;
+// task 1003768: the REBASE_REQUIRED 409 hint — exported so its wording is pinned
+// (tests/claim_gate_rebase.mjs). A remediation menu that names an impossible
+// command is how a builder loses twenty minutes at a gate they met with no context.
+module.exports.rebaseRequiredHint = rebaseRequiredHint;
 // task 1642: the pure session-scoped one-active-claim decision — exported for
 // tests/one_active_claim_per_session.mjs (DB-free) and reuse.
 module.exports.shouldRefuseSessionClaim = shouldRefuseSessionClaim;

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.686",
+  "version": "1.19.687",
   "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

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.686'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.687'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/api_path_404.mjs

@@ -6,8 +6,11 @@
 //      hint, never the HTML island page (which JSON.parse-faulted on the client).
 //   2. A TASK_NOT_READY 409 names the promote route instead of leaving the caller
 //      to spelunk for it (#506).
+//   3. A REBASE_REQUIRED 409 offers exits the reader's machine can actually take
+//      (task 1003768) — it used to lead with /merge-mode, which needs a GitHub push
+//      credential most builder machines deliberately lack.
 //
-// Both are pinned via the pure exported helpers (no server, no DB).
+// All three are pinned via the pure exported helpers (no server, no DB).
 //
 // Run:  node tests/api_path_404.mjs
 
@@ -16,7 +19,7 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 const { isApiShapedPath, apiPathHint, apiNotFoundBody } = require('../src/bongos/api-path-404.js');
-const { taskNotReadyHint } = require('../modules/lifecycle/routes/claims.js');
+const { taskNotReadyHint, rebaseRequiredHint } = require('../modules/lifecycle/routes/claims.js');
 
 let passed = 0;
 let failed = 0;
@@ -95,5 +98,51 @@ t('taskNotReadyHint: a non-backlog status is explained + still names promote', (
   assert.match(h, /POST \/api\/bongos\/tasks\/953\/promote/);
 });
 
+// ---- rebaseRequiredHint (the 409) ------------------------------------------
+// task 1003768. This gate fires at SESSION START and blocks every new claim, so a
+// builder meets it before they have any context — which makes each command it names
+// load-bearing. Pinned here rather than in tests/claim_gate_rebase.mjs because that
+// suite needs Postgres and sits in the INTEGRATION set, so a pin there would never
+// run in the gate that guards main.
+t('rebaseRequiredHint: leads with /strand-fix, the exit that works on any machine', () => {
+  const h = rebaseRequiredHint([{ id: 1003529 }]);
+  const strand = h.indexOf('/strand-fix');
+  const mergeMode = h.indexOf('/merge-mode');
+  // Both indices are asserted present before they are compared: indexOf returns -1
+  // for a missing needle, and -1 < anything, so a bare `strand < mergeMode` would
+  // report PASS on a hint that had dropped /strand-fix entirely.
+  assert.ok(strand >= 0, 'the hint must name /strand-fix');
+  assert.ok(mergeMode >= 0, 'this pin assumes /merge-mode is still mentioned; update it if that changes');
+  assert.ok(strand < mergeMode, 'the universally-available command must come before the credentialed-machine one');
+});
+
+t('rebaseRequiredHint: never offers /merge-mode unconditionally', () => {
+  const h = rebaseRequiredHint([{ id: 1003529 }]);
+  // Landing is server-mediated and most builder machines hold no push credential
+  // BY DESIGN (ADR 0031 §6 / ADR 0055) — naming /merge-mode without that condition
+  // sends the reader to a command that fails on auth.
+  assert.match(h, /push credential/);
+});
+
+t('rebaseRequiredHint: keeps /builder-release as the give-up exit', () => {
+  assert.match(rebaseRequiredHint([{ id: 7 }]), /\/builder-release/);
+});
+
+t('rebaseRequiredHint: names every gating task, and degrades to "unknown" on none', () => {
+  const h = rebaseRequiredHint([{ id: 11 }, { id: 22 }]);
+  assert.match(h, /task 11, task 22/);
+  assert.match(h, /2 confirmed task\(s\)/);
+  // A gate that cannot name its cause is the failure mode this hint exists to avoid.
+  assert.match(rebaseRequiredHint([]), /unknown/);
+  assert.match(rebaseRequiredHint(undefined), /unknown/, 'a missing list must not throw');
+});
+
+t('rebaseRequiredHint: says waiting is correct when CI is merely backed up', () => {
+  // learning 1000209: an exhausted Actions budget flags every confirmed task
+  // REBASE_REQUIRED, and there the right move is to WAIT — re-shipping or releasing
+  // makes it worse. Cheap to say in the menu; not cheaply detectable server-side.
+  assert.match(rebaseRequiredHint([{ id: 7 }]), /waiting is correct/);
+});
+
 console.log(`\napi_path_404: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);