@bongos/core 1.19.687 → 1.19.688

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.687",
-  "core_contract": "1.19.687",
-  "source_commit": "80529e693e8b33d02d80143fce82b5300e5f0c01",
+  "core_version": "1.19.688",
+  "core_contract": "1.19.688",
+  "source_commit": "51aa693c35073ab1ce7daa457af2e0e4d7fec69b",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T23:13:15.800Z",
+  "built_at": "2026-09-12T23:37:57.983Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 477,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2626,
-  "tree_sha256": "c85f4828bf21b1e106dfef13e6d603ea2774214cacdaf87ddbdb7f4242506e5c",
+  "tree_sha256": "816e4e976c2a1c41669cd3780f49542b0e1cfd53c429b6eed76083d4a5d9ca91",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f596cd52ec02d7e08108da8ce76a21a085aa1455989496d6a8501d1d7955ec5a"
+      "sha256": "ad6fde9308e83470ab3ec5edac298cbf8779592deeb3d3303a3059fdde18c84b"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7782,12 +7782,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "ad18930429a58c935061b8269dfea3c2fcbb1095eeff26859158679b9faf37d3"
+      "sha256": "9d60af5f5140c304e6e4246a248d24756f4aed5c467d8939957243e41104e1e4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "f4d3a3c0536c755502e2f9bafaf07a54fda378a3394b22e0a3a3368992300073"
+      "sha256": "84191b0fabaca6bd99dc874989f2c2a74e6574e9e7ee1b74345d05fbbc50650e"
     },
     {
       "path": "public-docs/index.html",
@@ -9287,7 +9287,7 @@
     {
       "path": "src/bongos/cascade-dispatch.js",
       "mode": "0000644",
-      "sha256": "b5401daa01d006ba239d882aa1acfddfc560f3505dd5437c829e7a553ee2662e"
+      "sha256": "7290d5d15b4c8283ebb17e28b17739b9dc5de4da3e916e9491248ba8acc24619"
     },
     {
       "path": "src/bongos/db-kernel.js",
@@ -9547,7 +9547,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "c323740fa5182f9e2c200cdbd349d19753cf7d6f2faee9cf98ff44ba13249d2f"
+      "sha256": "0cf41cdf014bc501350140b91d3cffe8c42cdb144375e53e8efdcc67c3f5ebb2"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10072,7 +10072,7 @@
     {
       "path": "tests/cascade-dispatch.mjs",
       "mode": "0000644",
-      "sha256": "de9d8f8c1daab1e48122febd16699ac519890b6e1296edb7966d835434851786"
+      "sha256": "5a537d6c4a3bcde720b95420fb41224f5169ae578d56b8d80f55043ddaa8113e"
     },
     {
       "path": "tests/catalog_only_client.mjs",
@@ -12757,7 +12757,7 @@
     {
       "path": "tests/sound_player.mjs",
       "mode": "0000644",
-      "sha256": "5b42ae4236e203c69feb3b8885ebec3a5f2b0d7f6880128536dfe5b8088fd4e8"
+      "sha256": "8d65bc64902312731e6b194af5be6336bcb59882adb930299cf43cf083977ca1"
     },
     {
       "path": "tests/sound_prefs.mjs",

package/docs/module-api-changelog.md

@@ -1833,5 +1833,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         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)
+  1.19.688 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.687 with no explicit bump. run 34725902871. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.687",
+  "version": "1.19.688",
   "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/bongos/cascade-dispatch.js

@@ -3,7 +3,9 @@
 // exceeding the per-builder ceiling. A mechanical task drafts on haiku; a
 // bug/refactor/feature drafts on sonnet; escalation to a higher rung happens only
 // when the cheaper run (a) fails its expected schema or (b) self-reports low
-// confidence — capped at 2 escalations. The cascade operates UNDER the builder's
+// confidence — capped at one full climb of the ladder (MAX_ESCALATIONS, derived
+// from LADDER so the cap can never sit below the ceiling a builder is allowed to
+// pick; task 1003664). The cascade operates UNDER the builder's
 // configured model ceiling (skill-prefs.getForBuilder, migration 037) — it can
 // downshift below it, never above.
 //
@@ -25,14 +27,33 @@
 const seams = require('../module-seams');
 
 // Cheapest → dearest. Indices are "rungs"; the cascade only ever moves UP.
-const LADDER = ['haiku', 'sonnet', 'opus'];
-const MAX_ESCALATIONS = 2;
+// `fable` tops the ladder: it is this instance's top-model default and prices
+// ABOVE opus ($10/$50 vs $5/$25 — llm-pricing.js PRICES), and the allowed-tier
+// list the settings UI writes agrees (modules/builder-settings/model-alloc-prefs.js
+// ALLOWED_TIERS). Without the rung, `claude-fable-5` fell through rungIndex's
+// unknown-model default and a fable CEILING silently clamped the cascade to
+// sonnet — one rung BELOW opus, the opposite of what that ceiling means
+// (task 1003664).
+const LADDER = ['haiku', 'sonnet', 'opus', 'fable'];
+
+// Enough escalations to climb from the CHEAPEST rung to the dearest — the
+// invariant the hardcoded `2` quietly satisfied while the ladder was 3 rungs
+// (haiku→opus is 2 steps) and stopped satisfying the moment fable was added: a
+// 'chore' starting on haiku with a fable ceiling would have run out of
+// escalations at opus and stopped one rung short, which is this task's own bug
+// wearing a different start rung. Derived, so a fifth rung cannot reintroduce it.
+// Per-call `maxEscalations` is unchanged and still overrides this.
+const MAX_ESCALATIONS = LADDER.length - 1;
 
 function rungIndex(model) {
   const m = String(model || '').toLowerCase();
   if (m.includes('haiku')) return 0;
   if (m.includes('sonnet')) return 1;
   if (m.includes('opus')) return 2;
+  // fable and mythos are ONE family at one price — the same pairing llm-pricing's
+  // familyFor() and grader-model's MODEL_FAMILY_TOKENS already make, so mythos
+  // must not fall through to the unknown default either.
+  if (m.includes('fable') || m.includes('mythos')) return 3;
   return 1; // unknown / 'script' / null → middle (sonnet); callers pass a real ceiling
 }
 

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.687'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.688'; // 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/cascade-dispatch.mjs

@@ -56,7 +56,7 @@ test('ceiling is NEVER exceeded — schema keeps failing but stops at sonnet cei
   assert.equal(r.ceiling, 'sonnet');
 });
 
-test('escalation capped at 2 (haiku → sonnet → opus, then stop)', async () => {
+test('a full climb from the cheapest rung reaches the ceiling (haiku → sonnet → opus)', async () => {
   const neverValid = () => false;
   const runner = mockRunner({});
   const r = await cascade.dispatch({ prompt: 'p', taskKind: 'chore', ceiling: 'opus', expectSchema: neverValid, runner });
@@ -64,6 +64,19 @@ test('escalation capped at 2 (haiku → sonnet → opus, then stop)', async () =
   assert.equal(r.escalations, 2);
 });
 
+// This one used to be the test above, named for the CAP — but with a 3-rung
+// ladder the cap and the opus ceiling stopped the climb at the same rung, so it
+// could not tell which one had acted. Drive the cap explicitly instead.
+test('the escalation cap stops a climb short of the ceiling when it is set below it', async () => {
+  const neverValid = () => false;
+  const runner = mockRunner({});
+  const r = await cascade.dispatch({
+    prompt: 'p', taskKind: 'chore', ceiling: 'fable', expectSchema: neverValid, runner, maxEscalations: 1,
+  });
+  assert.deepEqual(runner.calls, ['haiku', 'sonnet'], 'one escalation, then stop — well below the fable ceiling');
+  assert.equal(r.escalations, 1);
+});
+
 test('self-reported low confidence triggers escalation', async () => {
   const runner = mockRunner({ sonnet: LOWCONF, opus: GOOD });
   const r = await cascade.dispatch({ prompt: 'p', taskKind: 'feature', ceiling: 'opus', runner });
@@ -88,6 +101,70 @@ test('dispatch requires an injected runner', async () => {
   await assert.rejects(() => cascade.dispatch({ prompt: 'p', taskKind: 'bug', ceiling: 'opus' }), /requires an injected runner/);
 });
 
+// --- the fable rung (task 1003664) ------------------------------------------
+// A ceiling naming a model rungIndex does not recognise falls through to the
+// unknown default (1 = sonnet). For a ceiling that is meant to be the HIGHEST
+// rung that silently clamps the cascade BELOW opus — a downgrade dressed as a
+// ceiling, and invisible because nothing errors.
+
+test('a real fable model id resolves to the top rung, not the unknown default', async () => {
+  assert.equal(cascade.rungIndex('claude-fable-5'), 3, 'this is the bug: a fable id must not read as sonnet');
+  assert.equal(cascade.rungIndex('claude-fable-5-1'), 3);
+  assert.equal(cascade.rungIndex('fable'), 3);
+  // mythos is the same family at the same price everywhere else in the codebase.
+  assert.equal(cascade.rungIndex('claude-mythos-5-1'), 3);
+  assert.equal(cascade.rungIndex('mythos'), 3);
+  // the rung is above opus, which is the whole point
+  assert.ok(cascade.rungIndex('claude-fable-5') > cascade.rungIndex('claude-opus-5'));
+  assert.equal(cascade.LADDER[3], 'fable');
+});
+
+test('a fable ceiling escalates PAST opus instead of stopping at sonnet', async () => {
+  const neverValid = () => false;
+  const runner = mockRunner({});
+  const r = await cascade.dispatch({
+    prompt: 'p', taskKind: 'feature', ceiling: 'claude-fable-5', expectSchema: neverValid, runner,
+  });
+  assert.deepEqual(runner.calls, ['sonnet', 'opus', 'fable'], 'a fable ceiling must reach fable');
+  assert.equal(r.model, 'fable');
+  assert.equal(r.ceiling, 'fable');
+});
+
+// The haiku-start case, which the sonnet-start test above cannot see. A 4-rung
+// ladder needs 3 escalations to climb end-to-end; while MAX_ESCALATIONS was the
+// hardcoded 2 that a 3-rung ladder happened to satisfy, this stopped at opus —
+// the same "ceiling that doesn't reach its ceiling" bug, one start rung over.
+test('a chore with a fable ceiling climbs the WHOLE ladder, not just two rungs', async () => {
+  const neverValid = () => false;
+  const runner = mockRunner({});
+  const r = await cascade.dispatch({
+    prompt: 'p', taskKind: 'chore', ceiling: 'claude-fable-5', expectSchema: neverValid, runner,
+  });
+  assert.deepEqual(runner.calls, ['haiku', 'sonnet', 'opus', 'fable'], 'the cap must not sit below the ceiling');
+  assert.equal(r.model, 'fable');
+  assert.equal(r.escalations, 3);
+});
+
+test('the default cap always allows one full climb, whatever the ladder length', async () => {
+  assert.equal(cascade.MAX_ESCALATIONS, cascade.LADDER.length - 1, 'derive it — a fifth rung must not reintroduce the bug');
+});
+
+test('an opus ceiling still never reaches fable (the new rung is not a new floor)', async () => {
+  const neverValid = () => false;
+  const runner = mockRunner({});
+  const r = await cascade.dispatch({
+    prompt: 'p', taskKind: 'feature', ceiling: 'claude-opus-5', expectSchema: neverValid, runner,
+  });
+  assert.ok(!runner.calls.includes('fable'), 'fable must never be called above an opus ceiling');
+  assert.equal(r.model, 'opus');
+});
+
+test('an unknown model id still falls back to the safe middle', async () => {
+  assert.equal(cascade.rungIndex('script'), 1, 'the documented fallback is unchanged');
+  assert.equal(cascade.rungIndex(null), 1);
+  assert.equal(cascade.rungIndex(''), 1);
+});
+
 // settle async tests then report
 setTimeout(() => {
   console.log(`\ncascade-dispatch: ${passed} passed, ${failed} failed`);

package/tests/sound_player.mjs

@@ -355,29 +355,62 @@ test('playerFor never throws and returns null or a [cmd, args] pair', () => {
 // right for the DEFAULT call; it is wrong the moment a caller names a file.
 // ---------------------------------------------------------------------------
 
+// Runs in a CHILD with a sandboxed home, for the reason task 1003760 wrote up at
+// length in tests/cli_sessions.mjs: both prefs paths derive from os.homedir(), so
+// in-process this case reads the BUILDER'S OWN settings.
+//
+// That is what made it red (task 1003628). The old guard skipped only when the
+// LEGACY file existed, and then planted one — but it never checked the CANONICAL
+// file, and readPrefs consults legacy only when the canonical read THROWS. On any
+// machine with saved sound settings the canonical file parses, volume 100 comes
+// back, and the final assertion failed 100 !== 11. On a bare CI runner neither file
+// exists, the plant works, and it passed: green where nobody looks, red where
+// everybody does — the exact phrase this file's own comment above uses for the
+// product bug task 1003293 fixed. The product is correct; the test was reading the
+// developer's machine. Sandboxing is what makes the claim testable at all, rather
+// than skipped on every machine that has the state it cares about.
+//
+// Both layers of the 1003760 contract apply: override every variable a platform
+// might read for the home, and FAIL CLOSED in the child if os.homedir() did not
+// land in the sandbox — a silent escape here would plant a prefs file in the
+// builder's real config dir.
+function sandboxEnv(home) {
+  const { root } = path.parse(home);
+  return {
+    ...process.env,
+    HOME: home,
+    USERPROFILE: home,                          // Windows: what os.homedir() actually reads
+    HOMEDRIVE: root.replace(/[\\/]+$/, ''),     // legacy Windows fallback pair
+    HOMEPATH: home.slice(root.length - 1) || '\\',
+  };
+}
+
 test('an explicit missing path fails open — it never substitutes another file', () => {
-  // The regression: write a legacy-shaped prefs file at the pre-rename location
-  // and prove an explicit path still ignores it. Skipped if the real file exists,
-  // because this test must never clobber a builder's own settings.
-  const legacy = player.LEGACY_PREFS_PATH;
-  if (!legacy || fs.existsSync(legacy)) {
-    // Nothing to plant, but the invariant is still checkable: an absent explicit
-    // path must yield the fail-open default, whatever the legacy file holds.
-    const p = player.readPrefs(path.join(os.tmpdir(), `otb-absent-${process.pid}.json`));
-    assert.equal(p.volume, 100);
-    assert.equal(p.enabled('ship'), true);
-    return;
-  }
-  fs.mkdirSync(path.dirname(legacy), { recursive: true });
-  fs.writeFileSync(legacy, JSON.stringify({ volume: 11, ship: false }));
+  const home = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-sound-home-'));
   try {
-    const p = player.readPrefs(path.join(os.tmpdir(), `otb-absent-${process.pid}.json`));
-    assert.equal(p.volume, 100, 'an explicit path must not inherit the legacy file volume');
-    assert.equal(p.enabled('ship'), true, 'an explicit path must not inherit legacy mutes');
-    // …while the DEFAULT call still honours it — the fallback is not removed.
-    const d = player.readPrefs();
-    assert.equal(d.volume, 11, 'the default path must still fall back to the legacy file');
+    const code = `const R=${JSON.stringify(ROOT)};
+      const SANDBOX=${JSON.stringify(home)};
+      const os=require('node:os'), fs=require('node:fs'), path=require('node:path');
+      const assert=require('node:assert/strict');
+      if (os.homedir() !== SANDBOX) {
+        console.error('ERR sandbox-escape: os.homedir()=' + os.homedir() + ' but the sandbox is ' + SANDBOX
+          + ' — this platform does not take the home override, and planting prefs here would write to the real config dir.');
+        process.exit(2);
+      }
+      const player = require(R + '/.claude/sounds/play.js');
+      assert.ok(!fs.existsSync(player.PREFS_PATH), 'the sandbox must start with no canonical prefs file');
+      fs.mkdirSync(path.dirname(player.LEGACY_PREFS_PATH), { recursive: true });
+      fs.writeFileSync(player.LEGACY_PREFS_PATH, JSON.stringify({ volume: 11, ship: false }));
+      const p = player.readPrefs(path.join(os.tmpdir(), 'otb-absent-' + process.pid + '.json'));
+      assert.equal(p.volume, 100, 'an explicit path must not inherit the legacy file volume');
+      assert.equal(p.enabled('ship'), true, 'an explicit path must not inherit legacy mutes');
+      // …while the DEFAULT call still honours it — the fallback is not removed.
+      const d = player.readPrefs();
+      assert.equal(d.volume, 11, 'the default path must still fall back to the legacy file');
+      console.log('OK');`;
+    const r = execFileSync(process.execPath, ['-e', code], { encoding: 'utf8', env: sandboxEnv(home) });
+    assert.match(r, /OK/, 'the sandboxed child must reach its final assertion');
   } finally {
-    fs.unlinkSync(legacy);
+    fs.rmSync(home, { recursive: true, force: true });
   }
 });