@bongos/core 1.19.246 → 1.19.248

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.246",
-  "core_contract": "1.19.246",
-  "source_commit": "373c652f8aa8a3236479e5adf2cf25c3dd5bfa95",
+  "core_version": "1.19.248",
+  "core_contract": "1.19.248",
+  "source_commit": "bae0bacddfbacf9522b52c969f70eba97a404999",
   "source_ref": "HEAD",
-  "built_at": "2026-08-18T23:26:34.642Z",
+  "built_at": "2026-08-18T23:41:54.166Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 312,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1329,
+    "functional_verbatim": 1330,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1662,
-  "tree_sha256": "6cd3315e2da628addf8cf208857fb6be2124024c7504f5948eb402f3e59dd09c",
+  "file_count": 1663,
+  "tree_sha256": "e28385efcc78d3c913d04bce79e44e95394413c2e484ed96abffa7e8269d377c",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -4347,12 +4347,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "366c99418ef6e6309a86d726f762b53e9cfa16c829ac6192f23deb9ea16638d9"
+      "sha256": "16750ea8ecab7425183daae2d05d8f4aceb3769a03651b812ca520b5e1323801"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "2d61dd3140f0f188d6a928badfb8f7e29498e720ce35ee97174a7c05b5fc3467"
+      "sha256": "2dcfaaa9223a22671c43afcc5f0d3abac0db6d73193fc4a402e6d46bd04c519c"
     },
     {
       "path": "public-docs/index.html",
@@ -4847,7 +4847,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "83d27d14600c4c8ec8912c7ad8ce771e0e34903ccc9b567dcc27cb95aeb3c37d"
+      "sha256": "95574e210b1fd215b10c7664da109b0698b18aa7724daa736bade6d752318f63"
     },
     {
       "path": "scripts/gds/code.js",
@@ -5572,7 +5572,7 @@
     {
       "path": "scripts/gds/start.js",
       "mode": "0000644",
-      "sha256": "ecb7f326b9ef642e330b3f1d5dd68cf40ee76e451552291804b4a71a28cfab40"
+      "sha256": "cb37801c6ef35a64734af422c9651b287236c4d67f7ed72a63e1cd75a94d8b38"
     },
     {
       "path": "scripts/gds/status.js",
@@ -5972,7 +5972,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9ab5fbe6939d40d1c90001bbbe4b3f60c03620f43ddef279f199658b591c6ae5"
+      "sha256": "63a931fbe395426e0eaa09e2bb10cbbbdc247de66fcbdd836226dceaa45cac22"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6439,6 +6439,11 @@
       "mode": "0000644",
       "sha256": "b9258f690d5dc7c87bcbb12d510b3071a38669777ae9a92a99e683e76ea15e83"
     },
+    {
+      "path": "tests/cli_dispatcher.mjs",
+      "mode": "0000644",
+      "sha256": "3e3e17428a6c8f50ce0512cfacc4e18e0b6a2c506d185fa5f2adf21c9feffe9f"
+    },
     {
       "path": "tests/cli_exit_no_abort.mjs",
       "mode": "0000644",

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.246",
+  "version": "1.19.248",
   "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/cli-lib.js

@@ -141,6 +141,49 @@ function noKeepAliveDispatcher() {
   return _noKeepAliveDispatcher;
 }
 
+// task 1002670 — the vendored Agent above is only valid as a `dispatcher` for
+// Node's built-in fetch when the two undici copies speak the same internal
+// handler protocol. Node 26 bundles undici 8 while package.json overrides pin
+// the vendored copy at ^6, so built-in fetch rejects the v6 Agent with
+// InvalidArgumentError('invalid onError method') / UND_ERR_INVALID_ARG *before
+// any network I/O* — and every CLI then misreported a pure client-side bug as
+// "this instance isn't reachable yet". The pairing can't be predicted from
+// version numbers alone (a v6 Agent works fine under Node 24's undici 7), so
+// the selection is empirical: try the vendored Agent, and on the first
+// incompat rejection drop it for the rest of the process and retry the request
+// once on the default dispatcher.
+function isDispatcherIncompatError(err) {
+  const seen = new Set();
+  for (let e = err; e && typeof e === 'object' && !seen.has(e); e = e.cause) {
+    seen.add(e);
+    if (e.code === 'UND_ERR_INVALID_ARG' || e.name === 'InvalidArgumentError') return true;
+  }
+  return false;
+}
+
+// Test-only: reset the tried-once singleton so tests/cli_dispatcher.mjs can
+// exercise the selection/fallback from a clean slate regardless of what earlier
+// (real) requests did to it on this Node version.
+function _noKeepAliveResetForTest() {
+  _noKeepAliveDispatcher = undefined;
+  _noKeepAliveTried = false;
+}
+
+async function dispatchedFetch(url, init = {}, fetchImpl = fetch) {
+  const injected = init.dispatcher !== undefined && init.dispatcher === _noKeepAliveDispatcher;
+  try {
+    return await fetchImpl(url, init);
+  } catch (err) {
+    if (!injected || !isDispatcherIncompatError(err)) throw err;
+    // The vendored Agent is incompatible with this Node's built-in fetch.
+    // Stop offering it process-wide, then retry on the default dispatcher.
+    _noKeepAliveDispatcher = undefined;
+    const retry = { ...init };
+    delete retry.dispatcher;
+    return fetchImpl(url, retry);
+  }
+}
+
 // cliExit(code) — the post-request replacement for process.exit(code). Records the
 // exit status and lets node exit naturally once the loop drains, which is what
 // keeps the UV_HANDLE_CLOSING abort above from firing. Callers must `return` after
@@ -463,7 +506,7 @@ async function apiCall(method, urlPath, body = null, opts = {}) {
   // account billing, so identity is not an auth boundary. anthropic_user_id is
   // still kept in the session as cosmetic attribution; it is simply not
   // transmitted as a header.
-  const res = await fetch(`${base}${urlPath}`, {
+  const res = await dispatchedFetch(`${base}${urlPath}`, {
     method,
     headers,
     body: body ? JSON.stringify(body) : null,
@@ -531,7 +574,7 @@ async function cliClient(opts = {}) {
     init = init || {};
     init.headers = Object.assign({ 'User-Agent': CLI_USER_AGENT }, init.headers);
     if (init.dispatcher === undefined) init.dispatcher = noKeepAliveDispatcher();
-    const res = await fetch(url, init);
+    const res = await dispatchedFetch(url, init);
     if (res.status === 401 && !allowUnauthenticated && !_unauthExitInFlight) {
       _unauthExitInFlight = true;
       printUnauthGuidanceAndExit();
@@ -817,6 +860,10 @@ module.exports = {
   readSessionToken,
   apiCall,
   cliExit,
+  isDispatcherIncompatError,
+  dispatchedFetch,
+  noKeepAliveDispatcher,
+  _noKeepAliveResetForTest,
   cliClient,
   requireSession,
   printUnauthGuidanceAndExit,

package/scripts/gds/start.js

@@ -52,7 +52,7 @@
 //
 // Returns JSON if --json is passed (for the slash command to parse cleanly).
 
-const { cliClient, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge, hallBase, API_BASE, rewardPolicy, costPlusOnlyNote } = require('./cli-lib');
+const { cliClient, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge, hallBase, API_BASE, rewardPolicy, costPlusOnlyNote, isDispatcherIncompatError } = require('./cli-lib');
 const { contextPack, formatContextPackCompact } = require('./context-pack');
 const { depsFinding } = require('./preflight');
 
@@ -507,6 +507,10 @@ function rankCrossDisciplineRecommendations(claimable, preferredDisciplines, lim
 // builder-start skill routes those + the pre-install "bongos not found" case.
 function isConnectionError(err) {
   if (!err) return false;
+  // task 1002670: a dispatcher/argument bug (e.g. a vendored undici Agent the
+  // built-in fetch rejects with UND_ERR_INVALID_ARG) throws before any network
+  // I/O. That is a CLIENT bug — never present it as "instance isn't reachable".
+  if (isDispatcherIncompatError(err)) return false;
   const codes = ['ECONNREFUSED', 'ENOTFOUND', 'ECONNRESET', 'EAI_AGAIN', 'ETIMEDOUT', 'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_SOCKET'];
   const code = err.code || (err.cause && err.cause.code) || '';
   if (codes.includes(code)) return true;

package/src/module-api.js

@@ -919,8 +919,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.244 with no explicit bump. run 32196805853. (task 1002620)
 //   1.19.246 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.245 with no explicit bump. run 32197129803. (task 1002620)
+//   1.19.247 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.246 with no explicit bump. run 32197488065. (task 1002620)
+//   1.19.248 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.247 with no explicit bump. run 32198208766. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.246'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.248'; // 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/cli_dispatcher.mjs

@@ -0,0 +1,133 @@
+// tests/cli_dispatcher.mjs — dispatcher selection/fallback for the CLI fetch path
+// (task 1002670).
+//
+// THE BUG. cli-lib's noKeepAliveDispatcher() builds an Agent from the VENDORED
+// undici (package.json overrides pin ^6) and hands it to Node's BUILT-IN fetch as
+// `dispatcher`. Whether that pairing works is an internal-protocol accident of the
+// two undici versions: it works on Node 24 (built-in undici 7), and on Node 26
+// (built-in undici 8) it throws InvalidArgumentError('invalid onError method') /
+// UND_ERR_INVALID_ARG before any network I/O — and every CLI then misreported the
+// client-side bug as "this instance isn't reachable yet".
+//
+// THE CONTRACT PINNED HERE:
+//   1. isDispatcherIncompatError() recognizes the incompat shapes (top-level and
+//      wrapped in `cause`, per built-in fetch's TypeError('fetch failed')) and
+//      rejects genuine network-error shapes.
+//   2. dispatchedFetch() retries exactly once on the default dispatcher when the
+//      injected vendored Agent is rejected — and does NOT mask other failures or
+//      caller-supplied dispatchers.
+//   3. start.js's isConnectionError() returns false for the incompat shapes, so a
+//      dispatcher bug can never render the "instance isn't reachable" card.
+//   4. End-to-end on THIS Node: the real built-in fetch + the real vendored Agent
+//      reach a live local server (on Node 26 this is the case that used to die).
+//
+// Run:  node --test tests/cli_dispatcher.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cli = require('../scripts/gds/cli-lib.js');
+const { isConnectionError } = require('../scripts/gds/start.js');
+
+function incompatError() {
+  const cause = new TypeError('invalid onError method');
+  cause.name = 'InvalidArgumentError';
+  cause.code = 'UND_ERR_INVALID_ARG';
+  return new TypeError('fetch failed', { cause });
+}
+
+function connRefusedError() {
+  const cause = new Error('connect ECONNREFUSED 127.0.0.1:1');
+  cause.code = 'ECONNREFUSED';
+  return new TypeError('fetch failed', { cause });
+}
+
+test('isDispatcherIncompatError: recognizes UND_ERR_INVALID_ARG wrapped in cause', () => {
+  assert.equal(cli.isDispatcherIncompatError(incompatError()), true);
+});
+
+test('isDispatcherIncompatError: recognizes a bare InvalidArgumentError (no wrapper)', () => {
+  const err = new TypeError('invalid onError method');
+  err.name = 'InvalidArgumentError';
+  assert.equal(cli.isDispatcherIncompatError(err), true);
+});
+
+test('isDispatcherIncompatError: rejects genuine network errors', () => {
+  assert.equal(cli.isDispatcherIncompatError(connRefusedError()), false);
+  assert.equal(cli.isDispatcherIncompatError(new Error('socket hang up')), false);
+  assert.equal(cli.isDispatcherIncompatError(null), false);
+});
+
+test('isDispatcherIncompatError: survives a self-referential cause chain', () => {
+  const err = new Error('loop');
+  err.cause = err;
+  assert.equal(cli.isDispatcherIncompatError(err), false);
+});
+
+test('end-to-end on this Node: real fetch + vendored Agent reach a live server', async () => {
+  const server = http.createServer((req, res) => {
+    res.setHeader('content-type', 'application/json');
+    res.end(JSON.stringify({ ok: true, path: req.url }));
+  });
+  await new Promise((r) => server.listen(0, '127.0.0.1', r));
+  const { port } = server.address();
+  try {
+    // Exactly what apiCall does: built-in fetch, vendored no-keep-alive Agent
+    // injected. On Node 26 without the fallback this rejected before any I/O.
+    const res = await cli.dispatchedFetch(`http://127.0.0.1:${port}/api/gds/me`, {
+      method: 'GET',
+      headers: { 'Content-Type': 'application/json' },
+      dispatcher: cli.noKeepAliveDispatcher(),
+    });
+    assert.equal(res.status, 200);
+    const data = await res.json();
+    assert.equal(data.ok, true);
+  } finally {
+    server.close();
+  }
+});
+
+// NOTE: on Node 26 the end-to-end test above already fired the fallback and
+// dropped the singleton, so each test below resets it to a clean slate.
+
+test('dispatchedFetch: retries once without dispatcher when the vendored Agent is rejected', async () => {
+  cli._noKeepAliveResetForTest();
+  const vendored = cli.noKeepAliveDispatcher();
+  assert.ok(vendored !== undefined, 'vendored undici Agent should resolve in this repo');
+
+  const calls = [];
+  const fakeFetch = async (url, init) => {
+    calls.push(init.dispatcher);
+    if (init.dispatcher !== undefined) throw incompatError();
+    return { ok: true, status: 200 };
+  };
+  const res = await cli.dispatchedFetch('http://x/', { dispatcher: vendored }, fakeFetch);
+  assert.equal(res.status, 200);
+  assert.deepEqual(calls, [vendored, undefined]);
+
+  // After one incompat rejection the broken Agent is dropped process-wide:
+  // later calls get the default dispatcher instead of retrying the broken one.
+  assert.equal(cli.noKeepAliveDispatcher(), undefined);
+});
+
+test('dispatchedFetch: does not retry a caller-supplied dispatcher, or non-incompat errors', async () => {
+  const foreign = { name: 'someone-elses-dispatcher' };
+  let calls = 0;
+  const rejectingFetch = async () => { calls++; throw incompatError(); };
+  await assert.rejects(() => cli.dispatchedFetch('http://x/', { dispatcher: foreign }, rejectingFetch));
+  assert.equal(calls, 1);
+
+  calls = 0;
+  const networkFail = async () => { calls++; throw connRefusedError(); };
+  await assert.rejects(() => cli.dispatchedFetch('http://x/', {}, networkFail), /fetch failed/);
+  assert.equal(calls, 1);
+});
+
+test('start.js isConnectionError: dispatcher bug is NOT a connection error', () => {
+  assert.equal(isConnectionError(incompatError()), false);
+  assert.equal(isConnectionError(connRefusedError()), true);
+  assert.equal(isConnectionError(new Error('getaddrinfo ENOTFOUND nope.example')), true);
+});