@bongos/core 1.19.696 → 1.19.697

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.696",
-  "core_contract": "1.19.696",
-  "source_commit": "999c5518a84488c7cc2a016c7ca06b9331ee83fc",
+  "core_version": "1.19.697",
+  "core_contract": "1.19.697",
+  "source_commit": "bfb9b4492d0f0057725db35914055204f148c032",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T02:29:16.607Z",
+  "built_at": "2026-09-13T02:32:59.182Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 477,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2125,
+    "functional_verbatim": 2126,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2626,
-  "tree_sha256": "ef4cf6428521a6e96ab9c4568a06c28a2be79efe59d11cb876ff225ed3a88021",
+  "file_count": 2627,
+  "tree_sha256": "aecd13ccb73fd1082fe45b3aa23bab026afc2c358c584c4e188cb8caafcc1199",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "37285cc9f4e80f241192e4bd438b870f641b834bfac40011de3dca5560b5300a"
+      "sha256": "8862b2feb53917b00597c8a2a32d75fedbbe24cdb78c12998209f9de39395c15"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7772,12 +7772,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "cc9097410d73f9a032acff4b32a2b99196204ac471a5bf4ae8b88fa47a04b1d2"
+      "sha256": "b8fa92bf72071648e7a68331fcd48c316d5f42b4dd22ac58de8c69fa91cdbefb"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4ec1ea048ca3d3900d16773d1c62663fc61d4292670da335cab8c014cdba60cd"
+      "sha256": "1c2dd79228c1d4d99779ed0526734e6f75a68e40026db6665e800862b95cccc5"
     },
     {
       "path": "public-docs/index.html",
@@ -8697,7 +8697,7 @@
     {
       "path": "scripts/gds/run-unit-tests.js",
       "mode": "0000644",
-      "sha256": "e29e5f883205a94499ef0770ac71d517302c2e7079e48e1c9566d805dce6a245"
+      "sha256": "4ba19aaa0106bafafd6369b761460e0a1fccac3045f191c3f7835bc250623f40"
     },
     {
       "path": "scripts/gds/sandbox-stage.js",
@@ -9542,7 +9542,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "5f34fdf0e3931cb1bdce807abf20c9086f5a6795c5370a7e8911363f6cb36dd3"
+      "sha256": "aceceda426abd1aa9dd04fdfc69a225e7b33a91b790a823cf10d206698f24c1e"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12447,7 +12447,7 @@
     {
       "path": "tests/secret_box.mjs",
       "mode": "0000644",
-      "sha256": "1eb2218f483f63f28af363fb1f79cff6c79f3b83d5f152c004798e4fd3c5035d"
+      "sha256": "b50f33fe20bfa93f97c1250083bf0b4d36c72be75ddeffeef6ff7c2c0fe1cc62"
     },
     {
       "path": "tests/secret_gate.mjs",
@@ -12984,6 +12984,11 @@
       "mode": "0000644",
       "sha256": "a2ab80b7fb38695bb65c617eff1c39cfbe17403b1586cb1b20e3dee50e5a23fa"
     },
+    {
+      "path": "tests/unit_runner_serial.mjs",
+      "mode": "0000644",
+      "sha256": "024c65f27b684bc3a00181cd72df7e7152af3372c9338d9a38f0a1200c25b678"
+    },
     {
       "path": "tests/update_channel.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1851,5 +1851,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.694 with no explicit bump. run 34732266878. (task 1002620)
   1.19.696 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.695 with no explicit bump. run 34733145358. (task 1002620)
+  1.19.697 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.696 with no explicit bump. run 34733301156. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.696",
+  "version": "1.19.697",
   "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/run-unit-tests.js

@@ -284,6 +284,26 @@ function main() {
     }
   };
 
+  // EXECUTION IS SERIAL, ONE PROCESS PER TEST — and that is load-bearing, not
+  // incidental (task 1001435). runOne uses execFileSync, which blocks, and these
+  // are plain sequential loops: no Promise.all, no worker pool, no concurrency
+  // anywhere in this file. Pinned by tests/unit_runner_serial.mjs.
+  //
+  // Why it is written down. A flaky-`unit` report (this task, from idea #353)
+  // diagnosed "parallel execution racing on shared global state" and asked whether
+  // the runner fans tests out concurrently in one process. It does not, and never
+  // has — so an in-process race is ruled out as a cause by construction, and any
+  // future flake investigation should start somewhere else. The three suites that
+  // report named were audited then:
+  //   - fitness.mjs      — writes only under mkdtempSync(os.tmpdir()); no repo
+  //                        writes, no env mutation. Clean.
+  //   - session_index.mjs — mutates no global state at all. Clean.
+  //   - secret_box.mjs   — DID have a real hole, but not this one: it redirected
+  //                        only HOME, which os.homedir() ignores on Windows, so
+  //                        its sandbox was a no-op there. Fixed under this task.
+  // Collisions between separate processes remain possible through state OUTSIDE
+  // them — the real home directory, generated files in the repo, a second run on
+  // the same machine — which is where to look next, not here.
   for (const name of files) runOne(name, path.join(TESTS_DIR, `${name}.mjs`));
   for (const { key, name, file } of moduleTests) runOne(`${key}/${name}`, file);
 

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

@@ -6,16 +6,20 @@
 // tamper detection (a flipped byte fails the auth tag), wrong-key failure, and
 // the fail-closed isConfigured() behaviour.
 //
-// Hermetic: forces BUILDER_SECRET_KEY + HOME so the ~/.config/otb/builder-secret.key
-// fallback can't resolve to a real operator file on the test machine.
+// Hermetic: forces BUILDER_SECRET_KEY and redirects the HOME DIRECTORY — every
+// variable a platform might read for it, not HOME alone — so the
+// ~/.config/<instance>/builder-secret.key fallback cannot resolve to a real
+// operator file on the test machine. withKey then PROVES the redirect landed
+// (os.homedir() must be inside the sandbox) before running any body, and refuses
+// loudly if it did not. HOME alone was a no-op on Windows; see withKey (task 1001435).
 //
 // Run:  node tests/secret_box.mjs
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
 import { mkdtempSync, readFileSync, statSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
+import os, { tmpdir } from 'node:os';
+import path, { join } from 'node:path';
 import crypto from 'node:crypto';
 
 const require = createRequire(import.meta.url);
@@ -38,18 +42,69 @@ function t(name, fn) {
 const KEY_HEX = crypto.randomBytes(32).toString('hex');
 const OTHER_HEX = crypto.randomBytes(32).toString('hex');
 
-// Run a thunk with BUILDER_SECRET_KEY + an empty HOME, restoring both after.
+// Run a thunk with BUILDER_SECRET_KEY + an empty home, restoring everything after.
+//
+// SETTING HOME ALONE IS NOT ISOLATION (task 1001435, applying task 1003760's
+// contract). This file's header promises the real ~/.config/<instance>/
+// builder-secret.key "is never touched", and secret-box.js finds that file via
+// instance-config configHome() -> os.homedir(). On Windows os.homedir() reads
+// USERPROFILE and NEVER consults HOME, so the override below isolated nothing
+// there: the promise held on POSIX and was silently false on every Windows
+// checkout. Exactly the miss that cost real credentials in task 1003760, which
+// found ten files using this pattern and left the stragglers as task 1003763.
+//
+// No key file was in fact being written to the real config dir — measured before
+// changing this, by running the suite and checking the path — because every
+// provisioning case passes an explicit `file`. So this closes a LATENT hole, not
+// an active leak. It is still worth closing: the next case added here would
+// reasonably trust the header's promise, and the failure mode is destroying a
+// builder's own master key.
+// `home` is always an mkdtempSync(os.tmpdir()) path we just created, so the
+// HOMEDRIVE/HOMEPATH split below is plain string work on a value of our own making
+// — never attacker-influenced. If this shape is ever reused on an untrusted path,
+// split with path.win32 helpers instead of slicing.
+function sandboxHomeEnv(home) {
+  const { root } = path.parse(home);
+  return {
+    HOME: home,
+    USERPROFILE: home,                          // Windows: what os.homedir() actually reads
+    HOMEDRIVE: root.replace(/[\\/]+$/, ''),     // legacy Windows fallback pair
+    HOMEPATH: home.slice(root.length - 1) || '\\',
+  };
+}
+
 function withKey(keyValue, fn) {
   const origKey = process.env.BUILDER_SECRET_KEY;
-  const origHome = process.env.HOME;
   if (keyValue === null) delete process.env.BUILDER_SECRET_KEY;
   else process.env.BUILDER_SECRET_KEY = keyValue;
-  process.env.HOME = mkdtempSync(join(tmpdir(), 'otb-secretbox-'));
-  try { fn(); }
+
+  const home = mkdtempSync(join(tmpdir(), 'otb-secretbox-'));
+  const sandbox = sandboxHomeEnv(home);
+  const orig = {};
+  for (const k of Object.keys(sandbox)) orig[k] = process.env[k];
+  Object.assign(process.env, sandbox);
+  try {
+    // Layer 2 of the same contract: PROVE the override landed before running a
+    // body that can write a master key. os.homedir() re-reads the environment on
+    // every call (measured on win32: it follows USERPROFILE mid-process), so this
+    // is a real check, not a tautology. A future platform that reads some third
+    // variable fails here LOUDLY instead of quietly writing to the real config dir
+    // — the only acceptable outcome for a test whose subject is a secret file.
+    if (os.homedir() !== home) {
+      throw new Error(
+        `secret_box sandbox escape: os.homedir() is ${os.homedir()} but the sandbox is ${home} — `
+        + 'refusing to run, this would touch the real builder-secret.key.'
+      );
+    }
+    fn();
+  }
   finally {
     if (origKey === undefined) delete process.env.BUILDER_SECRET_KEY;
     else process.env.BUILDER_SECRET_KEY = origKey;
-    process.env.HOME = origHome;
+    for (const [k, v] of Object.entries(orig)) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
   }
 }
 
@@ -146,6 +201,25 @@ t('decrypt rejects a malformed blob', () => {
   });
 });
 
+// task 1001435: the isolation this file's header PROMISES, asserted instead of
+// assumed. Before this, withKey set HOME only — which on Windows os.homedir()
+// never reads — so the promise that the real builder-secret.key "is never
+// touched" was true on POSIX and false here, and nothing would have said so.
+t('withKey actually isolates the home dir — the header\'s promise, checked', () => {
+  const realHome = os.homedir();
+  let insideHome = null;
+  let insideConfig = null;
+  withKey(KEY_HEX, () => {
+    insideHome = os.homedir();
+    // The path secret-box.js would resolve for the key file, via the same
+    // instance-config chain it uses at runtime.
+    insideConfig = join(os.homedir(), '.config');
+  });
+  assert.notEqual(insideHome, realHome, 'the body must not see the builder\'s real home');
+  assert.ok(insideConfig.startsWith(insideHome), 'and the config dir must sit inside the sandbox');
+  assert.equal(os.homedir(), realHome, 'and the real home is restored afterwards');
+});
+
 console.log('\nprovisionMasterKey (task 1398 — productized, idempotent, never-overwrite):');
 
 // Split in two (task 1003529): the creation claim holds on every platform, the MODE

package/tests/unit_runner_serial.mjs

@@ -0,0 +1,72 @@
+// tests/unit_runner_serial.mjs
+//
+// The `unit` gate runs its tests SERIALLY, one child process each — pinned here
+// because that property is now load-bearing, not incidental (task 1001435).
+//
+// A flaky-`unit` report (idea #353) diagnosed "parallel execution racing on shared
+// global state" and asked, correctly, whether run-unit-tests fans tests out
+// concurrently in one process. It does not: runOne calls execFileSync, which
+// BLOCKS, from plain sequential for-loops. That rules an in-process race out by
+// construction, and scripts/gds/run-unit-tests.js now records the audit that
+// followed from it — including that two of the three suites the report named
+// (fitness, session_index) mutate no global state at all.
+//
+// All of that reasoning is only true while execution stays serial. Make the runner
+// concurrent and every word of it silently becomes wrong, with no test to say so —
+// so this suite fails if that happens, and whoever does it has to revisit the note
+// rather than leave a stale explanation behind.
+//
+// Static source assertions on purpose: actually observing concurrency would mean
+// running the whole gate from inside the gate.
+//
+// Run:  node tests/unit_runner_serial.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const RUNNER = path.join(ROOT, 'scripts', 'gds', 'run-unit-tests.js');
+const src = fs.readFileSync(RUNNER, 'utf8');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+t('each test runs in its OWN process, spawned synchronously', () => {
+  assert.match(src, /execFileSync\(\s*process\.execPath/,
+    'the runner must spawn each test with execFileSync (blocking, one process per test)');
+});
+
+t('the run loops are sequential — no concurrency primitive in the runner', () => {
+  // Promise.all / allSettled over the file list, a worker pool, or the async
+  // execFile would each make the suites overlap and reintroduce the shared-state
+  // class the recorded audit rules out.
+  assert.doesNotMatch(src, /Promise\.(all|allSettled|race)\s*\(/,
+    'a Promise.all over the test list would run suites concurrently');
+  assert.doesNotMatch(src, /require\(['"]node:worker_threads['"]\)|from ['"]node:worker_threads['"]/,
+    'a worker pool would run suites concurrently');
+  assert.doesNotMatch(src, /\bexecFile\s*\(/,
+    'the ASYNC execFile would overlap suites; the runner uses execFileSync');
+});
+
+t('the loop over the discovered test files is a plain for-of', () => {
+  assert.match(src, /for \(const name of files\) runOne\(/,
+    'sequential iteration is the mechanism — not a map() returning promises');
+});
+
+t('the serial guarantee is EXPLAINED where it is relied on, not just true by accident', () => {
+  // The audit recorded beside the loop is what a future flake investigation reads
+  // instead of re-deriving it. If the loop is rewritten the note must be revisited,
+  // which is the whole point of pinning it next to the mechanism.
+  assert.match(src, /EXECUTION IS SERIAL, ONE PROCESS PER TEST/,
+    'run-unit-tests.js must carry the note explaining why serialism is relied upon');
+});
+
+console.log('');
+console.log(`unit_runner_serial: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);