@bongos/core 1.19.38 → 1.19.39

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.38",
-  "core_contract": "1.19.38",
-  "source_commit": "ba6a8f6285476ab3cd4e33f9278b333ac0fc3a29",
+  "core_version": "1.19.39",
+  "core_contract": "1.19.39",
+  "source_commit": "d61c48b44f6f117383794f20d49b5bd7b83d35d7",
   "source_ref": "HEAD",
-  "built_at": "2026-08-11T16:17:20.571Z",
+  "built_at": "2026-08-11T16:25:51.076Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 288,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1521,
-  "tree_sha256": "9d55773209aeb85fef771e85aa30e901c52e54e155601030e44cd16fd5c46bda",
+  "tree_sha256": "14c889242599811c768effd9bc7ef844e4a6ee4ef0a041c74ff1629fda6f8907",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -3382,7 +3382,7 @@
     {
       "path": "modules/lifecycle/github-push.js",
       "mode": "0000644",
-      "sha256": "60b9338ed47d01e9f38fe3fa9f2f2cde6ff241b8e47efcb8fcf4c4f19d32c766"
+      "sha256": "9658ccf0dd332d6c4ce1e269c2966ebe2e2bed5f909d5d503722d8e8cfb1ebbc"
     },
     {
       "path": "modules/lifecycle/goal-advisory.js",
@@ -3437,7 +3437,7 @@
     {
       "path": "modules/lifecycle/publish-reconciler.js",
       "mode": "0000644",
-      "sha256": "964af2331007a4cfb9142e7245d7625cf21c973e4f885e0171855b9e188b9e95"
+      "sha256": "ad57ad242956c6ee3dc4aeddd66e980af48737fab644765aa3c400720f4a9668"
     },
     {
       "path": "modules/lifecycle/routes/analytics.js",
@@ -4022,12 +4022,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "413f575fce07ba5b167f6492a4f1aed1f7eacb4f4351457303d3875f04557787"
+      "sha256": "12291ed6b1927973c8d8c42c5384d7ba2368779b9a39c566336253069214cfb2"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "d0d31ac616a949591bca2975236bbf6d98437e969d1618bd68811620c2a130c3"
+      "sha256": "18139931183bcb89c64704ae5167ab99d1e8ae9841728870b277959af8523069"
     },
     {
       "path": "public-docs/index.html",
@@ -5647,7 +5647,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "2dfd2867ab83689497aff7a3b7f213e756c182e047ef8da754e098a945491ce7"
+      "sha256": "5f51d5f403c88eedf838dab85e4a9ddfa8ff575ec07b5f1189e12999001a335a"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -6417,7 +6417,7 @@
     {
       "path": "tests/github_push_merge_driver.mjs",
       "mode": "0000644",
-      "sha256": "1e038780532078d8d1a20feebb95ee6762fb300101f71cfff7076d2fa0d38b1b"
+      "sha256": "850113ed91babc9eb54dc22231f194d283fd3f94cee9deef1e6e0bf6f3a969c2"
     },
     {
       "path": "tests/github_repos_helpers.mjs",
@@ -7147,7 +7147,7 @@
     {
       "path": "tests/publish_reconciler.mjs",
       "mode": "0000644",
-      "sha256": "240337de03354de198d6baaaca9f33b267aceb40a8ba43d31303eb21fad9226c"
+      "sha256": "1aeb87a14e411160784c94ee5392f323a2ad0a373bd9acf91337289041e8d2bc"
     },
     {
       "path": "tests/rank_gate.mjs",

package/modules/lifecycle/github-push.js

@@ -675,6 +675,40 @@ async function mergeIfGreen({ branch }, deps = {}) {
   return { ...base, reason: `merge_api_${res.status}`, detail: detail.slice(0, 160) };
 }
 
+// task 1002666 — the carrier race. Publish-on-merge (ADR 0161) pushes a carrier
+// commit to main after EVERY land, so under an up-to-date branch-protection rule
+// a PR whose checks report after the previous merge's carrier goes BEHIND:
+// green, mergeable, and permanently stalled (GitHub's update-branch also disarms
+// auto-merge, so re-arming alone cannot recover it — observed on PR #48,
+// 2026-08-11). Server-side remedy: update the branch; checks re-run on the fresh
+// head and the next sweep's mergeIfGreen lands it. Fires ONLY on the definitive
+// BEHIND shape — GitHub reports the strict-up-to-date green-PR stall as BEHIND
+// once checks have reported; BLOCKED means checks are pending/missing and stays
+// untouched (updating there would loop on PRs that can never go green).
+// The state is re-read here even though the sweep's mergeIfGreen just read it:
+// update-branch is a WRITE, and the re-read guards against acting on a state
+// that changed between the two calls (e.g. the PR merged meanwhile) — the same
+// read-before-write discipline mergeIfGreen itself applies.
+async function updateBranchIfBehind({ branch }, deps = {}) {
+  const s = await getMergeState({ branch }, deps);
+  const base = { number: s.number, updated_now: false, merge_state: s.merge_state, reason: null };
+  if (s.merged) return { ...base, reason: 'already_merged' };
+  if (s.pr_state !== 'open') return { ...base, reason: 'no_open_pr' };
+  if (s.merge_state !== 'BEHIND') return { ...base, reason: mergeBlockReason(s) };
+  const token = await resolveToken(deps);
+  const repoInfo = deps.repoInfo || loadRepoInfo();
+  const { owner, repo } = repoInfo;
+  const doFetch = deps.fetchImpl || fetch;
+  const res = await doFetch(`https://api.github.com/repos/${owner}/${repo}/pulls/${s.number}/update-branch`, {
+    method: 'PUT',
+    headers: { ...ghHeaders(token), 'Content-Type': 'application/json' },
+    body: JSON.stringify(s.head_sha ? { expected_head_sha: s.head_sha } : {}),
+  });
+  if (res.ok) return { ...base, updated_now: true };
+  const detail = await res.text().catch(() => '');
+  return { ...base, reason: `update_api_${res.status}`, detail: detail.slice(0, 160) };
+}
+
 // task 1139 (ADR 0058): server-set commit status — the TRUSTLESS rank attestation the
 // gate-review CI check reads. Only the server (holding the App/PAT credential AND the
 // authenticated builder's server-resolved rank) can set it, so CI can trust it where it
@@ -1043,6 +1077,7 @@ module.exports = {
   getPublishStatus,
   getMergeState,
   mergeIfGreen,
+  updateBranchIfBehind,
   setCommitStatus,
   setGateOwnerApproved,
   listOpenPullRequests,

package/modules/lifecycle/publish-reconciler.js

@@ -200,6 +200,7 @@ async function runSweep(deps = {}) {
   let merged = 0;
   let resolvedConflicts = 0;
   let refreshedStale = 0; // task 1915: PRs whose stale generated indexes we regen+pushed
+  let behindUpdated = 0;  // task 1002666: green PRs behind main (carrier race) whose branch we updated
   let errors = 0;
   let unprovable = 0;   // confirmed tasks the sweep could not prove landed this pass
   let staleStrands = 0; // of those, the ones older than STALE_CONFIRMED_MS (WARN'd)
@@ -305,6 +306,38 @@ async function runSweep(deps = {}) {
             } catch (e) {
               errFn(`[publish-reconciler] conflict-resolve for task ${r.task_id} (non-blocking): ${e && e.message}`);
             }
+          } else if (
+            m && !m.merged && m.reason === 'branch_behind_base' &&
+            typeof push.updateBranchIfBehind === 'function'
+          ) {
+            // task 1002666: the ADR 0161 carrier race — every land pushes a
+            // carrier commit to main, so a green PR whose checks reported after
+            // the previous merge sits BEHIND forever (GitHub's update-branch
+            // disarms auto-merge, so it cannot recover on its own). Update the
+            // branch server-side; checks re-run on the fresh head and the NEXT
+            // sweep's mergeIfGreen lands it. Attempt-capped per branch on the
+            // shared heal map — on a hot fleet every update re-opens the race
+            // window, and a treadmill must surface, not spin.
+            const bKey = `behind:${branch}`;
+            const bn = attempts.get(bKey) || 0;
+            if (bn >= MAX_STALE_HEAL_ATTEMPTS) {
+              logFn(
+                `[publish-reconciler] task ${r.task_id} (${branch}) PR #${m.number} still behind main after ${bn} update-branch attempt(s) — capped (merge traffic is outracing this PR); left for a human`
+              );
+            } else {
+              attempts.set(bKey, bn + 1);
+              try {
+                const u = await push.updateBranchIfBehind({ branch });
+                if (u && u.updated_now) {
+                  behindUpdated++;
+                  logFn(
+                    `[publish-reconciler] task ${r.task_id} (${branch}) PR #${u.number} was green but behind main (carrier race) — server-updated the branch; checks re-run, lands next sweep`
+                  );
+                }
+              } catch (e) {
+                errFn(`[publish-reconciler] update-branch for task ${r.task_id} (non-blocking): ${e && e.message}`);
+              }
+            }
           } else if (
             m && couldBeStaleGenerated(m) &&
             typeof resolver.refreshStaleGenerated === 'function'
@@ -544,14 +577,17 @@ async function runSweep(deps = {}) {
   }
 
   // Prune the treadmill guard so it can't leak: a branch that left the confirmed set
-  // (landed, or released) never returns under the same name, so drop it.
+  // (landed, or released) never returns under the same name, so drop it. Keys may be
+  // namespaced ('behind:<branch>', task 1002666) — compare on the branch itself so a
+  // live branch's cap survives across sweeps and a departed branch's keys still prune.
   for (const b of attempts.keys()) {
-    if (!branchesSeen.has(b)) attempts.delete(b);
+    const plain = b.startsWith('behind:') ? b.slice('behind:'.length) : b;
+    if (!branchesSeen.has(plain)) attempts.delete(b);
   }
 
-  if (reconciled || merged || resolvedConflicts || refreshedStale) {
+  if (reconciled || merged || resolvedConflicts || refreshedStale || behindUpdated) {
     logFn(
-      `[publish-reconciler] swept ${rows.length} confirmed task(s); merged ${merged} stalled PR(s); auto-resolved ${resolvedConflicts} generated/index conflict(s); regen-healed ${refreshedStale} stale-generated PR(s); reconciled ${reconciled} → shipped`
+      `[publish-reconciler] swept ${rows.length} confirmed task(s); merged ${merged} stalled PR(s); auto-resolved ${resolvedConflicts} generated/index conflict(s); regen-healed ${refreshedStale} stale-generated PR(s); branch-updated ${behindUpdated} behind-main PR(s); reconciled ${reconciled} → shipped`
     );
   }
   if (staleStrands) {
@@ -559,7 +595,7 @@ async function runSweep(deps = {}) {
       `[publish-reconciler] ${staleStrands} stale strand(s): confirmed >${Math.round(STALE_CONFIRMED_MS / 60_000)}min with no provable land — credited but unlanded; see STRAND lines above`
     );
   }
-  return { checked: rows.length, reconciled, merged, resolvedConflicts, refreshedStale, errors, unprovable, staleStrands, strandsFlagged };
+  return { checked: rows.length, reconciled, merged, resolvedConflicts, refreshedStale, behindUpdated, errors, unprovable, staleStrands, strandsFlagged };
 }
 
 // task 1366 — server-side session-cost reconcile, piggybacked on the same 5-min

package/package-lock.json

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

package/package.json

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

@@ -503,8 +503,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.36 with no explicit bump. run 31510590459. (task 1002620)
 //   1.19.38 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.37 with no explicit bump. run 31511537558. (task 1002620)
+//   1.19.39 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.38 with no explicit bump. run 31512284325. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.38'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.39'; // 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/github_push_merge_driver.mjs

@@ -169,6 +169,64 @@ test('mergeBlockReason maps the common blocker states', () => {
   assert.equal(gh.mergeBlockReason({ ...open, merged: true }), null);
 });
 
+// --- task 1002666: updateBranchIfBehind (the carrier-race branch updater) ---
+
+// fetchImpl serving graphql + recording the update-branch PUT.
+function mkUpdateFetch({ node, updateStatus = 202 } = {}) {
+  const calls = { graphql: 0, update: 0, updateArgs: null };
+  const fetchImpl = async (url, opts = {}) => {
+    if (String(url).includes('/graphql')) {
+      calls.graphql++;
+      return {
+        ok: true, status: 200,
+        json: async () => ({ data: { repository: { pullRequests: { nodes: node ? [node] : [] } } } }),
+      };
+    }
+    if (String(url).includes('/update-branch')) {
+      calls.update++;
+      calls.updateArgs = { url, body: JSON.parse(opts.body || '{}') };
+      return {
+        ok: updateStatus >= 200 && updateStatus < 300,
+        status: updateStatus,
+        text: async () => '{}',
+      };
+    }
+    throw new Error(`unexpected fetch: ${url}`);
+  };
+  return { fetchImpl, calls };
+}
+
+test('updateBranchIfBehind updates a BEHIND PR, pinning the expected head sha', async () => {
+  const { fetchImpl, calls } = mkUpdateFetch({ node: prNode({ mergeStateStatus: 'BEHIND', oid: 'headsha' }) });
+  const u = await gh.updateBranchIfBehind({ branch: 'claude/wt' }, DEPS(fetchImpl));
+  assert.equal(u.updated_now, true);
+  assert.equal(calls.update, 1);
+  assert.match(String(calls.updateArgs.url), /\/pulls\/125\/update-branch$/);
+  assert.equal(calls.updateArgs.body.expected_head_sha, 'headsha', 'a raced head 422s instead of updating blind');
+});
+
+test('updateBranchIfBehind refuses every non-BEHIND shape without calling the API', async () => {
+  for (const [node, reason] of [
+    [prNode({ mergeStateStatus: 'CLEAN' }), 'clean'],
+    [prNode({ merged: true }), 'already_merged'],
+    [prNode({ state: 'CLOSED' }), 'no_open_pr'],
+    [prNode({ mergeStateStatus: 'BLOCKED' }), 'blocked_required_review_or_pending_check'],
+  ]) {
+    const { fetchImpl, calls } = mkUpdateFetch({ node });
+    const u = await gh.updateBranchIfBehind({ branch: 'claude/wt' }, DEPS(fetchImpl));
+    assert.equal(u.updated_now, false);
+    assert.equal(calls.update, 0, 'no update PUT for a non-BEHIND PR');
+    if (reason) assert.equal(u.reason, reason);
+  }
+});
+
+test('updateBranchIfBehind surfaces an API refusal as update_api_<status>', async () => {
+  const { fetchImpl } = mkUpdateFetch({ node: prNode({ mergeStateStatus: 'BEHIND' }), updateStatus: 403 });
+  const u = await gh.updateBranchIfBehind({ branch: 'claude/wt' }, DEPS(fetchImpl));
+  assert.equal(u.updated_now, false);
+  assert.equal(u.reason, 'update_api_403');
+});
+
 setTimeout(() => {
   console.log(`\ngithub-push merge driver (task 1162) tests: ${passed} passed, ${failed} failed`);
   process.exit(failed > 0 ? 1 : 0);

package/tests/publish_reconciler.mjs

@@ -57,9 +57,10 @@ function mkDeps({
   broadcastImpl,
   conflictResolveImpl,
   refreshStaleImpl,
+  updateByBranch = {},
   healAttempts = new Map(),
 } = {}) {
-  const calls = { ship: [], broadcast: [], status: [], merge: [], ancestry: [], search: [], resolve: [], refresh: [], flag: [], events: [], logs: [], errors: [] };
+  const calls = { ship: [], broadcast: [], status: [], merge: [], ancestry: [], search: [], resolve: [], refresh: [], update: [], flag: [], events: [], logs: [], errors: [] };
   // isSafeBranch mirrors github-push's pattern enough for the test (rejects
   // option-like / traversal refs); we use the REAL module so the contract can't drift.
   const githubPush = require('../modules/lifecycle/github-push.js');
@@ -110,6 +111,15 @@ function mkDeps({
         if (f instanceof Error) throw f;
         return f || null;
       },
+      // task 1002666: the carrier-race branch updater. Default: no open PR (a
+      // no-op), so pre-1002666 tests keep their exact behavior. Script per
+      // branch via updateByBranch; an Error value throws (swallowed, non-blocking).
+      updateBranchIfBehind: async ({ branch }) => {
+        calls.update.push(branch);
+        const u = updateByBranch[branch];
+        if (u instanceof Error) throw u;
+        return u || { updated_now: false, reason: 'no_open_pr' };
+      },
       // task 1313 head_sha land-check. Default: not on main. An Error value throws
       // (to prove a transient compare-API miss is swallowed, leaving it for next sweep).
       isAncestorOfDefaultBranch: async ({ sha }) => {
@@ -790,6 +800,79 @@ test('1915 mergeable-but-red PR → regen-heal fires on the right branch; refres
   assert.equal(deps._calls.ship.length, 0, 'the heal never ships (no phantom-ship — land still needs the tip proof)');
 });
 
+// --- task 1002666: the carrier race — green PR behind main gets its branch updated ---
+
+// mergeIfGreen shape for a green, mergeable PR that fell behind main (the ADR 0161
+// carrier landed after this PR's checks reported).
+const behindGreen = (number = 48) => ({
+  pr_state: 'open', number, merged: false, merged_now: false, mergeable: 'MERGEABLE', reason: 'branch_behind_base',
+});
+
+test('1002666 green-but-behind PR (carrier race) → server updates the branch; NOT shipped this sweep', async () => {
+  const deps = mkDeps({
+    rows: [{ task_id: 500, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': { number: 48, updated_now: true, merge_state: 'BEHIND', reason: null } },
+  });
+  const r = await reconciler.runSweep(deps);
+  assert.equal(r.behindUpdated, 1, 'the behind PR was branch-updated');
+  assert.deepEqual(deps._calls.update, ['claude/wt-behind'], 'the update is invoked on exactly this task\'s branch');
+  assert.equal(r.reconciled, 0, 'no ship this sweep — checks re-run on the new head, lands next sweep');
+  assert.equal(deps._calls.ship.length, 0, 'the update never ships (land still needs the tip proof)');
+  assert.ok(deps._calls.logs.some((l) => /carrier race/.test(l)), 'the log names the carrier race');
+});
+
+test('1002666 update-branch attempts are capped on the shared heal map (a hot fleet must surface, not spin)', async () => {
+  const healAttempts = new Map([['behind:claude/wt-behind', 3]]);
+  const deps = mkDeps({
+    rows: [{ task_id: 501, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': { number: 48, updated_now: true } },
+    healAttempts,
+  });
+  const r = await reconciler.runSweep(deps);
+  assert.equal(deps._calls.update.length, 0, 'at the cap the updater is not invoked');
+  assert.equal(r.behindUpdated, 0);
+  assert.ok(deps._calls.logs.some((l) => /capped/.test(l)), 'the cap is logged, not silent');
+});
+
+test('1002666 the behind-cap ACCUMULATES across sweeps for a live branch (the prune must not reset it)', async () => {
+  const healAttempts = new Map();
+  const mk = () => mkDeps({
+    rows: [{ task_id: 503, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': { number: 48, updated_now: true } },
+    healAttempts,
+  });
+  for (let i = 1; i <= 3; i++) {
+    await reconciler.runSweep(mk());
+    assert.equal(healAttempts.get('behind:claude/wt-behind'), i, `attempt ${i} is remembered after the sweep's prune`);
+  }
+  const fourth = mk();
+  const r = await reconciler.runSweep(fourth);
+  assert.equal(fourth._calls.update.length, 0, 'the 4th sweep is capped — a permanently-behind PR surfaces instead of spinning');
+  assert.equal(r.behindUpdated, 0);
+  // A branch that LEAVES the confirmed set prunes its namespaced key too (no leak).
+  const empty = mkDeps({ rows: [], healAttempts });
+  await reconciler.runSweep(empty);
+  assert.equal(healAttempts.has('behind:claude/wt-behind'), false, 'departed branch prunes its behind: key');
+});
+
+test('1002666 an update-branch API failure is swallowed (non-blocking) and the sweep continues', async () => {
+  const deps = mkDeps({
+    rows: [{ task_id: 502, builder_id: 5, worktree_name: 'wt-behind' }],
+    statusByBranch: { 'claude/wt-behind': PENDING },
+    mergeByBranch: { 'claude/wt-behind': behindGreen() },
+    updateByBranch: { 'claude/wt-behind': new Error('update-branch 403') },
+  });
+  const r = await reconciler.runSweep(deps);
+  assert.equal(r.behindUpdated, 0);
+  assert.ok(deps._calls.errors.some((l) => /update-branch/.test(l)), 'the failure is logged to errFn');
+});
+
 test('1915 mergeable-but-red PR where regen yields NO diff → not healed, logged as a real check failure', async () => {
   const deps = mkDeps({
     rows: [{ task_id: 401, builder_id: 5, worktree_name: 'wt-realfail' }],