@bongos/core 1.19.686 → 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.686",
-  "core_contract": "1.19.686",
-  "source_commit": "8f52ba91e493a99b11854b478933ac337d300c17",
+  "core_version": "1.19.688",
+  "core_contract": "1.19.688",
+  "source_commit": "51aa693c35073ab1ce7daa457af2e0e4d7fec69b",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T21:51:30.504Z",
+  "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": "fe7db21bbf1cad87c2f341633ce01284a5dec1940e45febe42bb66534e623865",
+  "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": "048ac25e9d49525c5bbf927234ff4b2386134bc83978ac2c6ba1fcd86764d3a3"
+      "sha256": "ad6fde9308e83470ab3ec5edac298cbf8779592deeb3d3303a3059fdde18c84b"
     },
     {
       "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": "9d60af5f5140c304e6e4246a248d24756f4aed5c467d8939957243e41104e1e4"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "47a7ca80b0914f25810d596d5bce2393d5e3ee93bb302a82a34047c76799720d"
+      "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": "1da978ad0d4fe540320d997da64154fb2780d80c346d1888cf6789e85f1c455d"
+      "sha256": "0cf41cdf014bc501350140b91d3cffe8c42cdb144375e53e8efdcc67c3f5ebb2"
     },
     {
       "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",
@@ -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

@@ -1831,5 +1831,9 @@ 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)
+  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/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.688",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.686",
+      "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.686",
+  "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.686'; // 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/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);

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 });
   }
 });