@bongos/core 1.19.822 → 1.19.823

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.822",
-  "core_contract": "1.19.822",
-  "source_commit": "5a9c009cff17c2a500ff23f5d0de66a1b7f00477",
+  "core_version": "1.19.823",
+  "core_contract": "1.19.823",
+  "source_commit": "2dbaf2b0a9d49393d3f3daf6f501a09087b8a156",
   "source_ref": "HEAD",
-  "built_at": "2026-09-17T11:05:47.254Z",
+  "built_at": "2026-09-17T11:55:48.898Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 490,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2228,
+    "functional_verbatim": 2230,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2744,
-  "tree_sha256": "acbc13ab96c308bd0c0aa200c9dd1f6af1013ed6771c70730a797f7a1fb4a697",
+  "file_count": 2746,
+  "tree_sha256": "6b21d5cba0536e95777730af1de9c226f7d38a89997a4cb586847a39748e7f37",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2547,7 +2547,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "9182a3b88e6092a231f59db4220628cb8579244c8289350406f07187c959e644"
+      "sha256": "5236a1550b3f87d767e2f59479b3f2ef8859621f0c57bbd7a054b8d056c1a2ef"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7812,12 +7812,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "d13165aac1aea3612a3c5af1b5b14267acdde35f2a8d99482310c7a749f9761c"
+      "sha256": "ade8e48efd7ae7eaeb9f51472f731940ca866a1f0a8917de7dadab245428908b"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "0f9f0baab592f70e890e2a39e61dcf21c5170841f97b8c82cb16703c2a959756"
+      "sha256": "bd706beddc637ac4587a99436be805e327d7392306525124874ea39092fa6149"
     },
     {
       "path": "public-docs/index.html",
@@ -8212,7 +8212,7 @@
     {
       "path": "scripts/gds/deploy-divergence.js",
       "mode": "0000644",
-      "sha256": "4b77b2c878cace855ad979c66a7bbb0318199d10b1e0f114f79732db2b6cc203"
+      "sha256": "39879d5d26a325529620ab4fd180f133643d0e4c2a5a9ef92f8ee347ad0ba0d7"
     },
     {
       "path": "scripts/gds/design-sync.js",
@@ -8302,7 +8302,7 @@
     {
       "path": "scripts/gds/fetch-sound-prefs.js",
       "mode": "0000644",
-      "sha256": "0043a1af935e5dff7d807525eb6426310a8e6517af03f0506a86cb3296d38f74"
+      "sha256": "f2239bdd653ceda6f2595d454e618bff5273f46eb63d3cb6d8040190ee0125e9"
     },
     {
       "path": "scripts/gds/figma-design-sync.js",
@@ -8689,6 +8689,11 @@
       "mode": "0000644",
       "sha256": "9898b6f8e60b9f5ee4aeb9a023d1b68bb5bfbdf589eed10923a8e492716340ed"
     },
+    {
+      "path": "scripts/gds/probe-cache.js",
+      "mode": "0000644",
+      "sha256": "34d891e8ff58f0da957d300021210dbc34448fe676873b6b77e13ad3b7179d2e"
+    },
     {
       "path": "scripts/gds/prove-strict-versioning.js",
       "mode": "0000644",
@@ -9232,7 +9237,7 @@
     {
       "path": "scripts/gds/strand-watch.js",
       "mode": "0000644",
-      "sha256": "c7f9c997a6892e6ca083a03789b24524912632731ea550df6ee974f1ef05267e"
+      "sha256": "2a9959bd2e45046dadcda9982998a5b7163cef00b5d719ff299314daa5409770"
     },
     {
       "path": "scripts/gds/stray-unit-sweep.sh",
@@ -9722,7 +9727,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "782160b1ae7c1483c92337a589f92d8099a8bbee37005ea744c78bd4fcb5803c"
+      "sha256": "2ac366c05863ab86d0bdb5b3df3bf6f605e4edb0182a977c83c781cf503bf5b7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12344,6 +12349,11 @@
       "mode": "0000644",
       "sha256": "3c85d28ecc55e375988f3e55aee993c8c84220889678262d8207146c2772f3f5"
     },
+    {
+      "path": "tests/probe_cache.mjs",
+      "mode": "0000644",
+      "sha256": "26c734a1ab1996e1aff6197a9e0b19a448b28c772e0e75b00fee2433535c1193"
+    },
     {
       "path": "tests/profile_activity.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2118,5 +2118,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.820 with no explicit bump. run 35212866365. (task 1002620)
   1.19.822 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.821 with no explicit bump. run 35213847140. (task 1002620)
+  1.19.823 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.822 with no explicit bump. run 35218228051. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.822",
+  "version": "1.19.823",
   "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/deploy-divergence.js

@@ -321,7 +321,11 @@ async function main() {
   if (hasFlag('--line')) {
     const ms = Number(arg('--timeout-ms')) || DEFAULT_TIMEOUT_MS;
     try {
-      const one = line(await check({ timeoutMs: ms }));
+      // Shared across concurrent session starts (task 1003689): four sessions opened
+      // seconds apart asked this same question four times and all four timed out, which
+      // emits NO line — and silence from a truth-teller reads as "nothing to report".
+      const { cached } = require('./probe-cache.js');
+      const { value: one } = await cached('deploy-divergence-line', async () => line(await check({ timeoutMs: ms })));
       if (one) console.log(one);
     } catch { /* offline, no git, unreadable module-api — all silence */ }
     process.exitCode = 0;

package/scripts/gds/fetch-sound-prefs.js

@@ -36,10 +36,16 @@ function writeAtomic(targetPath, contents) {
   fs.renameSync(tmp, targetPath);
 }
 
-async function main() {
+// The network half, on its own so probe-cache can own it: cached() records a value
+// only when its producer RESOLVES, so a failed fetch leaves nothing cached and the
+// next session retries instead of inheriting a minute of "already done".
+//
+// Returns { soundData, eventData } or null. Null is an ordinary outcome — offline, a
+// timeout, or both endpoints refusing — and the caller writes nothing, which leaves
+// the prefs file exactly as the last good run left it (fail-open).
+async function fetchPrefs() {
   const sess = readSessionToken();
-  if (!sess) return; // not signed in — player fails open
-
+  if (!sess) return null;
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), FETCH_TIMEOUT_MS);
   let soundData = null;
@@ -57,15 +63,44 @@ async function main() {
         signal: ctrl.signal,
       }),
     ]);
-    if (!soundRes.ok && !eventRes.ok) return;
+    if (!soundRes.ok && !eventRes.ok) return null;
     if (soundRes.ok) soundData = await soundRes.json();
     if (eventRes.ok) eventData = await eventRes.json();
   } catch (_) {
-    return; // network/timeout — no-op
+    return null; // network/timeout — no-op
   } finally {
     clearTimeout(timer);
   }
 
+  return { soundData, eventData };
+}
+
+async function main() {
+  const sess = readSessionToken();
+  if (!sess) return; // not signed in — player fails open
+
+  // SHARED ACROSS CONCURRENT SESSION STARTS (task 1003689). This is the third of the
+  // three SessionStart hooks that call the server, and when four sessions open within
+  // seconds they contend and every hook in all four hits its timeout. Unlike the
+  // truth-tellers, a lost run here is invisible rather than merely silent: the prefs
+  // file simply keeps its previous contents.
+  //
+  // Which is also why skipping the write on a cache hit is correct — the file already
+  // holds what the previous run fetched, and these prefs change when a builder edits
+  // them in Settings, not between two sessions opened three seconds apart.
+  // The cache must be marked fresh only by a SUCCESSFUL fetch. The first cut cached
+  // Date.now() BEFORE fetching, so a failed or timed-out fetch still recorded 'done'
+  // and blocked every retry for the whole TTL - turning a transient network error into
+  // a minute of silently stale prefs. cached() writes its record only when the producer
+  // RESOLVES, so the work belongs inside it, the way strand-watch and deploy-divergence
+  // already do it.
+  const { cached } = require('./probe-cache.js');
+  const { value: fetched, from } = await cached('sound-prefs', async () => fetchPrefs());
+  if (from !== 'fresh') return;   // another session already fetched and wrote the file
+  if (!fetched) return;           // not signed in, offline, or both requests failed
+  const { soundData, eventData } = fetched;
+
+
   // effective_map is { <sound>: <bool> } for every known sound (defaults
   // already applied server-side); volume is the master 0-100 (#788). The local
   // file shape is { sounds: {...}, volume: N, event_sounds: {...} } — play.js

package/scripts/gds/strand-watch.js

@@ -245,7 +245,14 @@ async function main() {
   // deploy-divergence's identical comment).
   if (hasFlag('--line')) {
     try {
-      const one = line(await check(opts));
+      // SHARED ACROSS CONCURRENT SESSION STARTS (task 1003689). Four sessions opened
+      // within three seconds — one worktree per claim, the normal pattern here — used
+      // to make this same call four times and ALL of them timed out, which produces no
+      // line at all. Silence from a truth-teller is indistinguishable from 'nothing to
+      // report', so the brief was lost without a symptom. The first session to ask now
+      // answers for the rest.
+      const { cached } = require('./probe-cache.js');
+      const { value: one } = await cached('strand-watch-line', async () => line(await check(opts)));
       if (one) console.log(one);
     } catch { /* no session, offline, unreadable — all silence */ }
     process.exitCode = 0;

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

@@ -0,0 +1,200 @@
+// tests/probe_cache.mjs — one answer, shared by the sessions that start together
+// (task 1003689).
+//
+// THE MEASUREMENT THIS EXISTS FOR. SessionStart runs six hooks, three of which call the
+// server. Four sessions opened within three seconds — one worktree per claim, the normal
+// pattern here — and every hook in all four hit its 10-15s timeout, while the sessions
+// immediately before and after ran clean at ~5s on identical config.
+//
+// A timed-out SessionStart hook emits NO LINE, so the truth-teller briefs vanish. Silence
+// is indistinguishable from "nothing to report", which is the one thing these probes are
+// built not to be.
+//
+// The cache must therefore fail toward DOING THE WORK, never toward silence: every error
+// path below returns the producer's answer rather than nothing.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const pc = require('../scripts/gds/probe-cache.js');
+
+// fileURLToPath, never URL.pathname (fitness check 30 / task 1002889): a %20 or a
+// Windows drive slash makes require() throw at load, and CI's spaceless checkout
+// cannot see it.
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const fresh = () => `k-${Math.random().toString(36).slice(2)}`;
+
+test('the second asker does not repeat the call', async () => {
+  const k = fresh();
+  let calls = 0;
+  const produce = async () => { calls += 1; return `answer-${calls}`; };
+  const a = await pc.cached(k, produce, { ttlMs: 5000 });
+  const b = await pc.cached(k, produce, { ttlMs: 5000 });
+  assert.equal(calls, 1, 'the whole point: four sessions, one question');
+  assert.equal(a.from, 'fresh');
+  assert.equal(b.from, 'cache');
+  assert.equal(b.value, a.value);
+});
+
+test('an expired answer is asked again', async () => {
+  const k = fresh();
+  let calls = 0;
+  const produce = async () => { calls += 1; return calls; };
+  await pc.cached(k, produce, { ttlMs: 1 });
+  await new Promise((r) => setTimeout(r, 10));
+  const b = await pc.cached(k, produce, { ttlMs: 1 });
+  assert.equal(calls, 2, 'a cache that never expires is a lie, not a cache');
+  assert.equal(b.from, 'fresh');
+});
+
+test('a record from the FUTURE is treated as stale, not trusted forever', () => {
+  // A clock that jumped would otherwise pin a stale answer permanently.
+  assert.equal(pc.isFresh({ at: 5_000 }, 1_000, 4_000), false);
+  assert.equal(pc.isFresh({ at: 3_500 }, 1_000, 4_000), true);
+  assert.equal(pc.isFresh(null, 1_000, 4_000), false);
+  assert.equal(pc.isFresh({}, 1_000, 4_000), false);
+});
+
+test('two checkouts of the same instance do not read each other\'s answers', async () => {
+  const k = fresh();
+  const a = await pc.cached(k, async () => 'from-A', { ttlMs: 5000, scope: '/repo/a' });
+  const b = await pc.cached(k, async () => 'from-B', { ttlMs: 5000, scope: '/repo/b' });
+  assert.equal(a.value, 'from-A');
+  assert.equal(b.value, 'from-B', 'the scope is part of the key — a worktree must not inherit another\'s brief');
+});
+
+test('a producer that throws is NOT cached, and the error reaches the caller', async () => {
+  const k = fresh();
+  await assert.rejects(() => pc.cached(k, async () => { throw new Error('probe failed'); }, { ttlMs: 5000 }));
+  // and the next asker gets a real attempt, not a cached failure
+  const r = await pc.cached(k, async () => 'recovered', { ttlMs: 5000 });
+  assert.equal(r.value, 'recovered');
+  assert.equal(r.from, 'fresh', 'a failure must not be remembered as an answer');
+});
+
+// ---- the real scenario: four processes at once -----------------------------
+//
+// The unit cases above all run in ONE process, where a lock is trivially uncontended.
+// The measured failure is four SEPARATE processes starting within three seconds on a
+// cold cache — and the first cut of this cache did NOT fix it: with nothing cached and
+// the lock held, every waiter fell through and made the call anyway, so all four still
+// ran. This is the case that caught it.
+test('four concurrent PROCESSES on a cold cache produce ONE call, and all four get the answer', async () => {
+  const counter = path.join(os.tmpdir(), `bongos-probe-test-${Date.now()}.txt`);
+  try { fs.rmSync(counter, { force: true }); } catch { /* not there */ }
+  execFileSync(process.execPath, [path.join(REPO_ROOT, 'scripts', 'gds', 'probe-cache.js'), '--clear'], { encoding: 'utf8' });
+
+  const child = `
+    const pc = require(${JSON.stringify(path.join(REPO_ROOT, 'scripts', 'gds', 'probe-cache.js'))});
+    const fs = require('fs');
+    (async () => {
+      const r = await pc.cached('probe-cache-concurrency-test', async () => {
+        fs.appendFileSync(${JSON.stringify(counter)}, 'ran\\n');
+        await new Promise((res) => setTimeout(res, 400));
+        return 'the-answer';
+      }, { ttlMs: 30000 });
+      process.stdout.write(r.value);
+    })();
+  `;
+
+  const { spawn } = await import('node:child_process');
+  const results = await Promise.all([0, 1, 2, 3].map(() => new Promise((resolve) => {
+    const p = spawn(process.execPath, ['-e', child]);
+    let out = '';
+    p.stdout.on('data', (d) => { out += d; });
+    p.on('close', () => resolve(out.trim()));
+  })));
+
+  const ran = fs.existsSync(counter) ? fs.readFileSync(counter, 'utf8').trim().split('\n').filter(Boolean).length : 0;
+  try { fs.rmSync(counter, { force: true }); } catch { /* best effort */ }
+
+  assert.equal(ran, 1, `the probe must run ONCE across four concurrent starts; it ran ${ran}`);
+  assert.deepEqual(results, ['the-answer', 'the-answer', 'the-answer', 'the-answer'],
+    'and every session must still get its brief — trading a timeout for a silence would be no fix at all');
+});
+
+// ---- FOUR DIFFERENT WORKTREES (grade round 1) ------------------------------
+//
+// The test above spawns four processes from ONE directory, and it passed while the
+// cache was keyed on process.cwd() — which meant the fix did nothing for the case it
+// was built for. The measured failure is four sessions in FOUR DIFFERENT WORKTREES,
+// one per claim, so four cwds hashed to four keys and nothing was ever shared.
+//
+// A test that does not model the scenario proves the wrong thing. This one runs each
+// child from a different directory of the SAME checkout.
+test('four processes in DIFFERENT worktrees of one checkout still share the answer', async () => {
+  const counter = path.join(os.tmpdir(), `bongos-probe-wt-${Date.now()}.txt`);
+  try { fs.rmSync(counter, { force: true }); } catch { /* not there */ }
+  execFileSync(process.execPath, [path.join(REPO_ROOT, 'scripts', 'gds', 'probe-cache.js'), '--clear'], { encoding: 'utf8' });
+
+  // Four real directories inside this checkout — different cwds, one git common dir,
+  // which is exactly the shape of four claim worktrees.
+  const cwds = [REPO_ROOT, path.join(REPO_ROOT, 'scripts'), path.join(REPO_ROOT, 'tests'), path.join(REPO_ROOT, 'docs')]
+    .filter((d) => fs.existsSync(d));
+  assert.equal(cwds.length, 4, 'need four real directories in this checkout to model four worktrees');
+
+  const child = `
+    const pc = require(${JSON.stringify(path.join(REPO_ROOT, 'scripts', 'gds', 'probe-cache.js'))});
+    const fs = require('fs');
+    (async () => {
+      const r = await pc.cached('probe-cache-worktree-test', async () => {
+        fs.appendFileSync(${JSON.stringify(counter)}, 'ran\\n');
+        await new Promise((res) => setTimeout(res, 400));
+        return 'shared';
+      }, { ttlMs: 30000 });
+      process.stdout.write(r.value);
+    })();
+  `;
+
+  const { spawn } = await import('node:child_process');
+  const results = await Promise.all(cwds.map((cwd) => new Promise((resolve) => {
+    const p = spawn(process.execPath, ['-e', child], { cwd });
+    let out = '';
+    p.stdout.on('data', (d) => { out += d; });
+    p.on('close', () => resolve(out.trim()));
+  })));
+
+  const ran = fs.existsSync(counter) ? fs.readFileSync(counter, 'utf8').trim().split('\n').filter(Boolean).length : 0;
+  try { fs.rmSync(counter, { force: true }); } catch { /* best effort */ }
+
+  assert.equal(ran, 1, `four DIFFERENT working directories must still share one answer; the probe ran ${ran} times`);
+  assert.deepEqual(results, ['shared', 'shared', 'shared', 'shared']);
+});
+
+test('the scope is the CHECKOUT, not the directory', () => {
+  // Every worktree of one checkout reports the same git common dir; two unrelated
+  // checkouts report different ones. That is the distinction that matters, because the
+  // probes ask one server about one repo.
+  const scope = pc.defaultScope();
+  assert.ok(scope && typeof scope === 'string');
+  assert.ok(/\.git$|\.git[\\/]/.test(scope) || scope === process.cwd(),
+    `expected a git common dir (or the documented cwd fallback), got ${scope}`);
+});
+
+test('clear() with no argument actually empties the cache', async () => {
+  // It used to take a scope and delete only when that was exactly null — so calling it
+  // with its own default deleted nothing while reporting success.
+  const k = fresh();
+  let calls = 0;
+  await pc.cached(k, async () => { calls += 1; return calls; }, { ttlMs: 60_000 });
+  pc.clear();
+  await pc.cached(k, async () => { calls += 1; return calls; }, { ttlMs: 60_000 });
+  assert.equal(calls, 2, 'after clear(), the next asker must do the work again');
+});
+
+test('the three SessionStart hooks that call the server all go through the cache', () => {
+  // The wiring is the deliverable; the cache alone changes nothing. These are the three
+  // that make network calls — the other three SessionStart hooks are local git.
+  for (const rel of ['scripts/gds/strand-watch.js', 'scripts/gds/deploy-divergence.js', 'scripts/gds/fetch-sound-prefs.js']) {
+    const src = fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
+    assert.match(src, /require\('\.\/probe-cache\.js'\)/, `${rel} must share its answer with concurrent sessions`);
+    assert.match(src, /cached\(/, `${rel} must actually call cached(), not merely import it`);
+  }
+});