@bongos/core 1.19.696 → 1.19.698

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.698",
+  "core_contract": "1.19.698",
+  "source_commit": "8fb86a2225d9ed2a99fe253ea3886c7b2e7bcfc9",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T02:29:16.607Z",
+  "built_at": "2026-09-13T02:48:21.644Z",
   "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": "53de7b22ab854dd4a788f5ce3827fca83328bb1f43e0415eae9528923e68596b",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "37285cc9f4e80f241192e4bd438b870f641b834bfac40011de3dca5560b5300a"
+      "sha256": "5c48de96a5d2d3ed794c4f503a665f0c4defc7d06f384ba4012eeb02cf3036aa"
     },
     {
       "path": "docs/modules-contract.md",
@@ -4267,7 +4267,7 @@
     {
       "path": "modules/dev-box/box-access.js",
       "mode": "0000644",
-      "sha256": "7bc7c746f2518cb465773a205c8e9fe7efc30852c857001255be92ad8e340bca"
+      "sha256": "7271dc2c3eab6c8ed274dc90f855ec813eef4e401180a300e31de31dce30aa6c"
     },
     {
       "path": "modules/dev-box/box-credential.js",
@@ -7772,12 +7772,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "cc9097410d73f9a032acff4b32a2b99196204ac471a5bf4ae8b88fa47a04b1d2"
+      "sha256": "0faabe7f40491c6ab374488d6ae4a244694e1fbf40c280ad98ef0a249c207b80"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4ec1ea048ca3d3900d16773d1c62663fc61d4292670da335cab8c014cdba60cd"
+      "sha256": "f623a28e95671e15f28bc19bc1b29f26f00312c5f0dc5e8761b872dd42e85923"
     },
     {
       "path": "public-docs/index.html",
@@ -8072,7 +8072,7 @@
     {
       "path": "scripts/gds/context-pack.js",
       "mode": "0000644",
-      "sha256": "caa5dd1628b00569a5593964f1831641ac12c9a85b8ec132964a1baf67c77350"
+      "sha256": "7863284f9d81a9cf77a5d01cff82d119207637090f9ef14012c8689625e93a49"
     },
     {
       "path": "scripts/gds/control-manifest.js",
@@ -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": "f03b116eece1a5517cda1bf812627f7148aaf2827806d53d70f3b67d343026ab"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9922,7 +9922,7 @@
     {
       "path": "tests/box_access.mjs",
       "mode": "0000644",
-      "sha256": "911a764f72976298daa17855acb836d0ada3215b480961ae8607e1fc3634f882"
+      "sha256": "85b0f479d16d53eea0442cab9ea8aa2dd09d95926765b47a142c609af22f6927"
     },
     {
       "path": "tests/box_auth_check.mjs",
@@ -10232,7 +10232,7 @@
     {
       "path": "tests/context_pack.mjs",
       "mode": "0000644",
-      "sha256": "09f956c01f169ab7384204a5d43deefa3e57a7d57924072dfa8215f0942c2513"
+      "sha256": "159661396a274740d9164dce8532b54e283ead733301c841078334033784d04f"
     },
     {
       "path": "tests/control_manifest.mjs",
@@ -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,9 @@ 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)
+  1.19.698 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.697 with no explicit bump. run 34733917938. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/dev-box/box-access.js

@@ -178,6 +178,24 @@ const BASE_SPARSE_PATHS = [
   // config/government.json) is host content the box's own builder authors — no
   // credentials live here (ADR 0022); those are in /etc and the box env.
   'config',
+  // modules/lifecycle — task 1003085. BASE's whole charter is "enough to run the
+  // /builder-* CLI", and the CLI does not run without this module:
+  // scripts/gds/context-pack.js reads the task enums from
+  // modules/lifecycle/task-classifier, and context-pack is on the /builder-start
+  // AND /builder-claim paths. On a task-scoped box with NO active claim nothing
+  // put lifecycle in scope, so both commands died at import with MODULE_NOT_FOUND
+  // — and neither could be used to fix it, because a CLAIM is what fetches the
+  // module. The only way out was POST /claims by hand.
+  //
+  // This is the structural half; context-pack.js also degrades now if the module
+  // is absent for any OTHER reason. Both, deliberately: the degrade keeps the CLI
+  // alive against a future module gap, and this line is what makes the pack
+  // actually COMPLETE on every box rather than quietly reduced.
+  //
+  // Same posture as the entries above — core-domain work-tracking code, which is
+  // methodology and not product runtime, so it belongs in BASE by the same reading
+  // that put scripts/ and src/bongos/ here. No secrets; a cone-mode directory.
+  'modules/lifecycle',
 ];
 
 // sparsePathsForScopeKeys — PURE. Given the module KEYS a builder's active claims

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.696",
+  "version": "1.19.698",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.696",
+      "version": "1.19.698",
       "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.698",
   "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/context-pack.js

@@ -30,11 +30,30 @@ const path = require('node:path');
 // The live validators. task-classifier is a pure module (no DB, no network),
 // so importing it from a CLI is safe — same precedent as next-number.js reading
 // the repo tree directly. This is the "not hand-maintained" guarantee.
-const {
-  VALID_KINDS,
-  VALID_DISCIPLINES,
-  TASK_FIELD_BOUNDS,
-} = require('../../modules/lifecycle/task-classifier');
+//
+// OPTIONAL, because the file may not be ON DISK (task 1003085). A task-scoped box
+// (ADR 0148) materializes modules/<key> only for the modules the CLAIM puts in
+// scope, so on a box with NO active claim modules/lifecycle is absent and this
+// require threw MODULE_NOT_FOUND at import time. That killed /builder-start AND
+// /builder-claim — the exact two commands needed to escape the state, since the
+// claim is what would fetch the module. A deadlock, escapable only by calling
+// POST /claims with curl. The header's FAIL-OPEN promise ("must NEVER throw or
+// block a claim") was already the right rule; this require was the line that did
+// not keep it.
+//
+// Degrade by OMITTING the enums, NEVER by hard-coding a copy. A local list of
+// kinds is precisely the drift the "generated from the live validators" design
+// exists to prevent, and it would be WORSE than absence: absence costs the
+// planner one /docs lookup, while a stale list reads as authoritative and is
+// discovered only when POST /tasks rejects it — the guess-and-retry turn this
+// whole pack was built to save.
+let classifier = null;
+try {
+  // eslint-disable-next-line global-require
+  classifier = require('../../modules/lifecycle/task-classifier');
+} catch (_) {
+  // Not materialized on this box. apiContract() reports it honestly below.
+}
 
 // Single source of truth for the API prefix (src/bongos/api-prefix.js) so the URL
 // rename (Part B) flips one constant and this pack follows. Importing a pure src
@@ -46,17 +65,31 @@ const { API_PREFIX } = require('../../src/bongos/api-prefix');
 // The API contract a planner needs to file/claim without guessing. 'unclassified'
 // is dropped from both enums: it's the classifier's fallback bucket, never a
 // value a human should pick.
+//
+// The SHAPE is the same either way — empty arrays and null bounds, never missing
+// keys — because every consumer here and in start.js reads these fields
+// positionally. Returning a short object instead would move the crash from the
+// require to the formatter and fix nothing. `enums_available` is what the
+// formatters branch on, so "we don't know" is said once, in words, rather than
+// rendered as an empty list that looks like "there are none".
 function apiContract() {
-  const kinds = [...VALID_KINDS].filter((k) => k !== 'unclassified');
-  const disciplines = [...VALID_DISCIPLINES].filter((d) => d !== 'unclassified');
-  return {
+  const base = {
     api_prefix: API_PREFIX,
     docs_url: '/docs',
     openapi_url: '/docs/openapi.json',
-    task_kinds: kinds,
-    disciplines,
-    priority: TASK_FIELD_BOUNDS.priority,
-    manual_degree: TASK_FIELD_BOUNDS.manual_degree,
+    enums_available: Boolean(classifier),
+    task_kinds: [],
+    disciplines: [],
+    priority: null,
+    manual_degree: null,
+  };
+  if (!classifier) return base;
+  return {
+    ...base,
+    task_kinds: [...classifier.VALID_KINDS].filter((k) => k !== 'unclassified'),
+    disciplines: [...classifier.VALID_DISCIPLINES].filter((d) => d !== 'unclassified'),
+    priority: classifier.TASK_FIELD_BOUNDS.priority,
+    manual_degree: classifier.TASK_FIELD_BOUNDS.manual_degree,
   };
 }
 
@@ -212,13 +245,20 @@ function formatContextPack(pack) {
   lines.push(`  Held claims:    ${formatClaims(claims)}`);
   lines.push(`  API prefix:     ${api.api_prefix}   (e.g. POST ${api.api_prefix}/tasks, GET ${api.api_prefix}/me)`);
   lines.push(`  API reference:  ${api.docs_url} (rendered) · ${api.openapi_url} (OpenAPI 3.1)`);
-  lines.push(`  Task kinds:     ${api.task_kinds.join(', ')}`);
-  lines.push(`  Disciplines:    ${api.disciplines.join(', ')}`);
-  const conv = api.priority.convention;
-  lines.push(
-    `  Numeric fields: priority int ${api.priority.min}–${api.priority.max} ` +
-    `(use ${conv.label}) · manual_degree int ${api.manual_degree.min}–${api.manual_degree.max}`
-  );
+  if (api.enums_available) {
+    lines.push(`  Task kinds:     ${api.task_kinds.join(', ')}`);
+    lines.push(`  Disciplines:    ${api.disciplines.join(', ')}`);
+    const conv = api.priority.convention;
+    lines.push(
+      `  Numeric fields: priority int ${api.priority.min}–${api.priority.max} ` +
+      `(use ${conv.label}) · manual_degree int ${api.manual_degree.min}–${api.manual_degree.max}`
+    );
+  } else {
+    // Say WHY and WHERE to look. The one thing this line must not do is imply the
+    // enums are empty — a planner who reads "kinds:" with nothing after it will
+    // invent one.
+    lines.push(`  Task kinds:     unavailable here — modules/lifecycle is not on this box; see ${api.docs_url}`);
+  }
   lines.push(`  OS:             ${formatOs(os)}`);
   return lines.join('\n');
 }
@@ -230,7 +270,9 @@ function formatContextPack(pack) {
 // noise beyond the shared compass.
 function formatContextPackCompact(pack) {
   const { worktree, api } = pack;
-  const kinds = api.task_kinds.slice(0, 4).join(', ') + (api.task_kinds.length > 4 ? ', …' : '');
+  const kinds = api.enums_available
+    ? api.task_kinds.slice(0, 4).join(', ') + (api.task_kinds.length > 4 ? ', …' : '')
+    : `see ${api.docs_url}`;
   return [
     `🧭 Worktree: ${worktree.root}  (edit + git here, not the main checkout)`,
     `   API ${api.api_prefix} · kinds: ${kinds} · full pack on /builder-claim`,

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.698'; // 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/box_access.mjs

@@ -196,7 +196,12 @@ console.log('\nBASE_SPARSE_PATHS — the non-product base a task-scoped box laye
 t('BASE carries the methodology + tooling, NOT the product/game', () => {
   // clients/ is load-bearing: cli-lib.js hard-imports clients/bongos-client, so a
   // cone without it has a fully dead builder CLI on the box (task 1002745).
-  for (const p of ['.devcontainer', '.claude', 'scripts', 'src/bongos', 'docs', 'infra', 'tests', 'clients']) {
+  // modules/lifecycle is load-bearing for the same reason (task 1003085):
+  // scripts/gds/context-pack.js reads the task enums from its task-classifier,
+  // and context-pack sits on BOTH /builder-start and /builder-claim. A box with
+  // no active claim put nothing in scope, so both commands died at import — and
+  // neither could fix it, because a CLAIM is what fetches the module.
+  for (const p of ['.devcontainer', '.claude', 'scripts', 'src/bongos', 'docs', 'infra', 'tests', 'clients', 'modules/lifecycle']) {
     assert.ok(BASE.includes(p), `BASE must include ${p}`);
   }
   for (const p of ['src/world', 'src/rooms', 'public', 'art', 'modules/status-ui']) {

package/tests/context_pack.mjs

@@ -339,5 +339,85 @@ t('formatContextPackCompact: two lines, worktree + prefix, no undefined', () =>
   assert.ok(!/undefined/.test(out));
 });
 
+// ---- the task-scoped box with no claim (task 1003085) ----------------------
+//
+// A box scoped to a claim materializes modules/<key> only for the modules that
+// claim put in scope (ADR 0148). With NO active claim, modules/lifecycle is not
+// on disk — and this file's hard `require` of task-classifier threw
+// MODULE_NOT_FOUND at IMPORT time, which killed /builder-start and
+// /builder-claim: the two commands needed to escape the state, because a claim
+// is what fetches the module. The live escape was POST /claims by curl.
+//
+// This reproduces the condition for real rather than asserting on source text:
+// a temp tree holding context-pack.js and the one other thing it imports, with
+// NO modules/ directory at all. A regression re-introducing a bare top-level
+// require fails here at `require(...)`, before any assertion runs.
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const url = require('node:url');
+
+function boxWithoutLifecycle() {
+  const here = path.dirname(url.fileURLToPath(import.meta.url));
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'ctxpack-nolifecycle-'));
+  fs.mkdirSync(path.join(root, 'scripts', 'gds'), { recursive: true });
+  fs.mkdirSync(path.join(root, 'src', 'bongos'), { recursive: true });
+  fs.copyFileSync(path.join(here, '..', 'scripts', 'gds', 'context-pack.js'),
+    path.join(root, 'scripts', 'gds', 'context-pack.js'));
+  // The ONLY other import. Deliberately copied rather than stubbed: if
+  // context-pack grows a second hard dependency, this test fails and that new
+  // coupling has to be looked at — which is the point.
+  fs.copyFileSync(path.join(here, '..', 'src', 'bongos', 'api-prefix.js'),
+    path.join(root, 'src', 'bongos', 'api-prefix.js'));
+  // No modules/ — that IS the box condition.
+  assert.ok(!fs.existsSync(path.join(root, 'modules')), 'the fixture must not carry modules/');
+  return { root, mod: require(path.join(root, 'scripts', 'gds', 'context-pack.js')) };
+}
+
+t('a box with no modules/lifecycle can still LOAD the pack (the deadlock)', () => {
+  const { mod } = boxWithoutLifecycle();
+  const api = mod.apiContract();
+  assert.equal(api.enums_available, false, 'it must say so, not pretend');
+  assert.equal(api.api_prefix, '/api/bongos', 'everything not behind the module still works');
+  // Shape preserved, so every positional consumer survives.
+  assert.deepEqual(api.task_kinds, []);
+  assert.deepEqual(api.disciplines, []);
+  assert.equal(api.priority, null);
+  assert.equal(api.manual_degree, null);
+});
+
+t('both formatters render on that box instead of throwing', () => {
+  const { mod } = boxWithoutLifecycle();
+  const pack = mod.buildContextPack({
+    activeClaims: [], cwd: '/fallback', platform: 'linux',
+    runGit: () => '/work/tree\n', runWhich: () => '',
+  });
+  // The crash this moves is subtle: omitting the keys instead of emptying them
+  // would just relocate the failure from the require to `api.priority.convention`
+  // here — still a dead CLI, one stack frame later.
+  const full = mod.formatContextPack(pack);
+  assert.ok(!/undefined/.test(full), 'no undefined leaks into the pack');
+  assert.match(full, /unavailable here/, 'it names the gap');
+  assert.match(full, /\/docs/, 'and says where the real answer is');
+  assert.doesNotMatch(full, /Task kinds: {5}$/m, 'never an EMPTY kinds line — that reads as "there are none"');
+  const compact = mod.formatContextPackCompact(pack);
+  assert.equal(compact.split('\n').length, 2);
+  assert.ok(!/undefined/.test(compact));
+});
+
+t('with the module present the enums are still the LIVE ones, not a local copy', () => {
+  // The guard on the fix: degrading must not have introduced a hand-maintained
+  // fallback list. This is the original design promise, re-pinned against the
+  // new code path.
+  const api = apiContract();
+  assert.equal(api.enums_available, true);
+  const live = require('../modules/lifecycle/task-classifier');
+  assert.deepEqual(api.task_kinds, [...live.VALID_KINDS].filter((k) => k !== 'unclassified'));
+  assert.deepEqual(api.disciplines, [...live.VALID_DISCIPLINES].filter((d) => d !== 'unclassified'));
+  const src = fs.readFileSync(new URL('../scripts/gds/context-pack.js', import.meta.url), 'utf8');
+  assert.doesNotMatch(src, /'(bug|feature|chore|cleanup|verify)'\s*,\s*'/,
+    'a literal kind list in this file is the drift the generated design exists to prevent');
+});
+
 console.log(`\ncontext_pack: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

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