@bongos/core 1.18.0 → 1.18.18

package/tests/box_access.mjs

@@ -76,7 +76,7 @@ t('cloneSpecForScope: starter sparsePaths is a COPY (mutating it cannot poison t
 console.log('\nSTARTER_SPARSE_PATHS — the scoped surface (ADR 0052 §9.2):');
 
 t('starter surface includes the build tooling + game runtime', () => {
-  for (const p of ['.claude', 'scripts', 'src/bongos', 'src/world', 'src/rooms', 'public', '.devcontainer', 'infra']) {
+  for (const p of ['.claude', 'scripts', 'src/bongos', 'src/world', 'src/rooms', 'public', '.devcontainer', 'infra', 'tests']) {
     assert.ok(access.STARTER_SPARSE_PATHS.includes(p), `starter scope must include ${p}`);
   }
 });
@@ -182,5 +182,134 @@ t('reconcileSourceAccess: inactivity outranks an otherwise in-sync full Metic bo
   assert.deepEqual(d, { action: 'deprovision', reason: 'builder-inactive' });
 });
 
+// ===========================================================================
+// TASK-SCOPED source access (ADR 0148 / goal 1000051, R93). BASE_SPARSE_PATHS,
+// the pure sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) cone-filter, and
+// the decideSourceAccess three-way branch. Uses the REAL module-scope-map (a pure
+// core module) as the map the route (R94) will pass in.
+// ===========================================================================
+const scopeMap = require('../src/bongos/module-scope-map.js');
+const BASE = access.BASE_SPARSE_PATHS;
+
+console.log('\nBASE_SPARSE_PATHS — the non-product base a task-scoped box layers on:');
+
+t('BASE carries the methodology + tooling, NOT the product/game', () => {
+  for (const p of ['.devcontainer', '.claude', 'scripts', 'src/bongos', 'docs', 'infra', 'tests']) {
+    assert.ok(BASE.includes(p), `BASE must include ${p}`);
+  }
+  for (const p of ['src/world', 'src/rooms', 'public', 'art', 'modules/status-ui']) {
+    assert.ok(!BASE.includes(p), `BASE must NOT include the product surface ${p}`);
+  }
+});
+
+console.log('\nsparsePathsForScopeKeys — BASE ∪ the claims’ module DIRS (cone-mode):');
+
+t('no keys (empty array) → BASE only, in declared order', () => {
+  assert.deepEqual(access.sparsePathsForScopeKeys([], scopeMap), [...BASE]);
+});
+
+t('one key → BASE + that module’s directory (status-ui → modules/status-ui)', () => {
+  const out = access.sparsePathsForScopeKeys(['status-ui'], scopeMap);
+  assert.deepEqual(out, [...BASE, 'modules/status-ui']);
+});
+
+t('cone-filter: dev-box keeps its DIRS, DROPS its file globs (scripts/gds/box.js)', () => {
+  const out = access.sparsePathsForScopeKeys(['dev-box'], scopeMap);
+  assert.ok(out.includes('modules/dev-box'), 'the module dir is kept');
+  assert.ok(out.includes('devbox-app'), 'the app dir is kept');
+  assert.ok(!out.some((p) => p.endsWith('.js') || p.endsWith('.sh')), 'no file globs survive the cone filter');
+  assert.ok(!out.includes('scripts/gds/box.js'), 'the box CLI file is dropped (BASE scripts covers it)');
+});
+
+t('cone-filter: the kernel key contributes only its real DIR globs (config, src/module-loader)', () => {
+  const out = access.sparsePathsForScopeKeys(['kernel'], scopeMap);
+  // kernel is mostly individual src/bongos/*.js FILES (dropped — BASE src/bongos
+  // covers them via cone ancestor-inclusion) + a few genuine DIR globs.
+  assert.ok(out.includes('config'), 'config/ is a real dir the task needs, not in BASE');
+  assert.ok(out.includes('src/module-loader'), 'src/module-loader/ is a real dir not in BASE');
+  assert.ok(!out.includes('src/bongos/db.js'), 'the kernel FILE globs are dropped');
+  assert.ok(!out.includes('server.js'), 'top-level files never enter the sparse set (cone auto-includes them)');
+});
+
+t('N keys → union, deduped + sorted; unknown keys contribute nothing', () => {
+  const out = access.sparsePathsForScopeKeys(['status-ui', 'hall-ui'], scopeMap);
+  assert.deepEqual(out, [...BASE, 'modules/hall-ui', 'modules/status-ui'], 'union of both dirs, sorted');
+  assert.deepEqual(access.sparsePathsForScopeKeys(['status-ui', 'status-ui'], scopeMap), [...BASE, 'modules/status-ui'], 'dedup');
+  assert.deepEqual(access.sparsePathsForScopeKeys(['bogus'], scopeMap), [...BASE], 'unknown key → no extra paths');
+});
+
+t('missing/!scopeForModule moduleScopeMap → BASE only (guards the missing map)', () => {
+  assert.deepEqual(access.sparsePathsForScopeKeys(['dev-box'], null), [...BASE]);
+  assert.deepEqual(access.sparsePathsForScopeKeys(['dev-box'], {}), [...BASE]);
+});
+
+console.log('\ndecideSourceAccess — the ADR 0148 three-way (rank still gates ALLOW/DENY):');
+
+t('scopeKeys present + non-empty → TASK scope, BASE ∪ the module dirs (rank no longer caps breadth)', () => {
+  const d = access.decideSourceAccess({ rank: 'xenos', status: 'active', scopeKeys: ['status-ui'], moduleScopeMap: scopeMap });
+  assert.equal(d.allowed, true);
+  assert.equal(d.scope, 'task');
+  assert.equal(d.spec.mode, 'sparse');
+  assert.deepEqual(d.spec.sparsePaths, [...BASE, 'modules/status-ui'], 'even a Xenos with a claim gets the claim’s module scope');
+});
+
+t('scopeKeys present + EMPTY → BASE-only (a live box with no active claim)', () => {
+  const d = access.decideSourceAccess({ rank: 'metic', status: 'active', scopeKeys: [], moduleScopeMap: scopeMap });
+  assert.equal(d.allowed, true);
+  assert.equal(d.scope, 'base');
+  assert.deepEqual(d.spec.sparsePaths, [...BASE], 'idle Metic+ now gets BASE-only, not the whole repo (ADR 0148 flagged change)');
+});
+
+t('scopeKeys ABSENT → the pre-ADR-0148 RANK fallback is preserved EXACTLY (R93-before-R94 safety)', () => {
+  assert.equal(access.decideSourceAccess({ rank: 'metic', status: 'active' }).scope, 'full', 'no claim signal → rank fallback (full)');
+  assert.equal(access.decideSourceAccess({ rank: 'xenos', status: 'active' }).scope, 'starter', 'no claim signal → rank fallback (starter)');
+});
+
+t('the ALLOW/DENY gates run BEFORE scope selection', () => {
+  const inactive = access.decideSourceAccess({ rank: 'metic', status: 'inactive', scopeKeys: ['status-ui'], moduleScopeMap: scopeMap });
+  assert.equal(inactive.allowed, false);
+  assert.equal(inactive.reason, 'BUILDER_INACTIVE');
+  const belowFloor = access.decideSourceAccess({ rank: 'xenos', status: 'active', floor: 'metic', scopeKeys: ['status-ui'], moduleScopeMap: scopeMap });
+  assert.equal(belowFloor.allowed, false);
+  assert.equal(belowFloor.reason, 'INSUFFICIENT_RANK');
+});
+
+console.log('\nscopeMetadata — the credential-FREE projection for GET /box/scope (BV1.R100):');
+
+t('task scope → modules deduped+sorted, sparse_paths carried, NO credential fields', () => {
+  const scopeKeys = ['dev-box', 'onboarding', 'dev-box']; // dup on purpose
+  const decision = access.decideSourceAccess({ rank: 'metic', status: 'active', scopeKeys, moduleScopeMap: scopeMap });
+  const meta = access.scopeMetadata({ decision, scopeKeys });
+  assert.equal(meta.scope, 'task');
+  assert.equal(meta.mode, 'sparse');
+  assert.deepEqual(meta.modules, ['dev-box', 'onboarding'], 'deduped + sorted');
+  assert.ok(Array.isArray(meta.sparse_paths) && meta.sparse_paths.includes('modules/dev-box'));
+  assert.ok(!('credential' in meta) && !('repo_url' in meta), 'never carries credential fields');
+});
+
+t('empty claims → base scope, modules is [] (not null) — a live box with no active claim', () => {
+  const decision = access.decideSourceAccess({ rank: 'metic', status: 'active', scopeKeys: [], moduleScopeMap: scopeMap });
+  const meta = access.scopeMetadata({ decision, scopeKeys: [] });
+  assert.equal(meta.scope, 'base');
+  assert.deepEqual(meta.modules, []);
+  assert.deepEqual(meta.sparse_paths, [...BASE]);
+});
+
+t('rank fallback (scopeKeys absent) → modules is null (breadth is rank-driven, not per-module)', () => {
+  const decision = access.decideSourceAccess({ rank: 'metic', status: 'active' });
+  const meta = access.scopeMetadata({ decision, scopeKeys: undefined });
+  assert.equal(meta.scope, 'full');
+  assert.equal(meta.mode, 'full');
+  assert.equal(meta.modules, null);
+});
+
+t('a DENIED decision projects to null (the route returns 403, never a scope body)', () => {
+  const denied = access.decideSourceAccess({ rank: 'xenos', status: 'inactive', scopeKeys: [], moduleScopeMap: scopeMap });
+  assert.equal(denied.allowed, false);
+  assert.equal(access.scopeMetadata({ decision: denied, scopeKeys: [] }), null);
+  assert.equal(access.scopeMetadata({}), null, 'no decision → null');
+  assert.equal(access.scopeMetadata(), null, 'no args → null');
+});
+
 console.log(`\nbox_access.mjs: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/box_credential.mjs

@@ -0,0 +1,125 @@
+// tests/box_credential.mjs
+//
+// R102 (goal 1000051, ADR 0148 C4) — VERIFY the server-side-token posture holds
+// once source scope is CLAIM-based (R92–R94). The security property task-scoping
+// must not weaken: the GitHub credential is server-issued per fetch from the prod
+// ENV (never the repo — ADR 0022), the box never receives a fabricated token, and
+// the claim-scoped ACCESS DECISION carries NO secret — the token is minted
+// SEPARATELY, so changing what the box materializes (sparse paths) never touches
+// the token model.
+//
+// Pure + hermetic: makeEnvCredentialProvider takes an injected env; decideSourceAccess
+// is pure. NO env, NO network, NO box. The DEFERRED hardening (short-lived per-claim
+// credential + hard "can't over-pull" isolation) is documented in ADR 0148 C4 /
+// Consequences — this test pins the posture that ships TODAY.
+//
+// Run:  node tests/box_credential.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cred = require('../modules/dev-box/box-credential.js');
+const access = require('../modules/dev-box/box-access.js');
+const scopeMap = require('../src/bongos/module-scope-map.js');
+
+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}`); }
+}
+
+const REPO = 'https://github.com/acme/portable-core.git';
+const STARTER_REPO = 'https://github.com/acme/starter-surface.git';
+
+console.log('box-credential — the token is SERVER-ENV sourced, never fabricated (ADR 0022):');
+
+t('no env configured → configured:false + token:null (the box gets guidance, not a token)', () => {
+  const p = cred.makeEnvCredentialProvider({});
+  for (const scope of ['full', 'starter']) {
+    const c = p.issue(scope, { nowMs: 0 });
+    assert.equal(c.configured, false, `${scope}: unconfigured`);
+    assert.equal(c.token, null, `${scope}: NO token is ever fabricated`);
+    assert.equal(c.repoUrl, null, `${scope}: no repo without env`);
+    assert.match(c.guidance || '', /env/i, `${scope}: guidance points at the prod env`);
+  }
+});
+
+t('repo set but token unset → still configured:false (no partial/empty-token leak)', () => {
+  const c = cred.makeEnvCredentialProvider({ BOX_SOURCE_REPO_URL: REPO }).issue('full', { nowMs: 0 });
+  assert.equal(c.configured, false);
+  assert.equal(c.token, null);
+});
+
+t('token comes STRAIGHT from the env var — and lands ONLY in .token, no other field', () => {
+  const p = cred.makeEnvCredentialProvider({
+    BOX_SOURCE_REPO_URL: REPO,
+    BOX_SOURCE_FULL_TOKEN: 'FULL-SECRET-abc',
+    BOX_SOURCE_STARTER_TOKEN: 'STARTER-SECRET-xyz',
+  });
+  const full = p.issue('full', { nowMs: 0 });
+  assert.equal(full.token, 'FULL-SECRET-abc', 'full scope → the FULL env token, verbatim');
+  const starter = p.issue('starter', { nowMs: 0 });
+  assert.equal(starter.token, 'STARTER-SECRET-xyz', 'starter scope → the STARTER env token, verbatim');
+  // The secret must appear in NO field other than `token` (scope/repoUrl/guidance/
+  // expiresAt/ttl are safe to log + audit — see the source_grant audit).
+  for (const c of [full, starter]) {
+    for (const [k, v] of Object.entries(c)) {
+      if (k === 'token') continue;
+      assert.ok(!String(v).includes(c.token), `secret must not leak into .${k}`);
+    }
+  }
+});
+
+console.log('\nbox-credential — the credential SCOPE is rank-based; scope can never over-reach the repo:');
+
+t('a separate starter repo is a HARD boundary: only "full" reaches the full repo', () => {
+  const p = cred.makeEnvCredentialProvider({
+    BOX_SOURCE_REPO_URL: REPO,
+    BOX_SOURCE_STARTER_REPO_URL: STARTER_REPO,
+    BOX_SOURCE_FULL_TOKEN: 'F',
+    BOX_SOURCE_STARTER_TOKEN: 'S',
+  });
+  assert.equal(p.issue('full', { nowMs: 0 }).repoUrl, REPO, 'full → the full repo');
+  const starter = p.issue('starter', { nowMs: 0 });
+  assert.equal(starter.repoUrl, STARTER_REPO, 'starter → the SEPARATE starter repo, cannot reach the full one');
+  assert.equal(starter.separateStarterRepo, true);
+});
+
+t('fail-closed: an UNEXPECTED scope label ("task"/"base") never escalates to the full repo', () => {
+  // R94 passes only rank scopes ('starter'|'full') to issue(); this pins the safety
+  // margin if a task/base label ever reached it — it takes the NON-full (starter)
+  // branch, so on a separate-starter-repo instance it can't reach the crown jewels.
+  const p = cred.makeEnvCredentialProvider({
+    BOX_SOURCE_REPO_URL: REPO,
+    BOX_SOURCE_STARTER_REPO_URL: STARTER_REPO,
+    BOX_SOURCE_FULL_TOKEN: 'F',
+    BOX_SOURCE_STARTER_TOKEN: 'S',
+  });
+  for (const label of ['task', 'base', 'wizard', undefined]) {
+    const c = p.issue(label, { nowMs: 0 });
+    assert.equal(c.repoUrl, STARTER_REPO, `scope='${label}' must NOT reach the full repo`);
+    assert.notEqual(c.token, 'F', `scope='${label}' must NOT get the full-only token`);
+  }
+});
+
+console.log('\ntask-scoping decoupling — the claim-scoped ACCESS DECISION carries NO secret:');
+
+t('decideSourceAccess returns scope/mode/sparsePaths only — the token is minted separately', () => {
+  const d = access.decideSourceAccess({ rank: 'metic', status: 'active', scopeKeys: ['dev-box'], moduleScopeMap: scopeMap });
+  assert.equal(d.allowed, true);
+  assert.deepEqual(Object.keys(d.spec).sort(), ['mode', 'scope', 'sparsePaths'], 'the spec is scope/mode/sparsePaths — NO credential field');
+  const blob = JSON.stringify(d);
+  assert.ok(!/token|credential|secret|ghp_|github_pat/i.test(blob), 'the decision blob holds no secret-shaped field');
+});
+
+t('revocation scrubs at the credential layer: an inactive/below-floor builder is denied BEFORE any credential', () => {
+  const inactive = access.decideSourceAccess({ rank: 'metic', status: 'inactive', scopeKeys: ['dev-box'], moduleScopeMap: scopeMap });
+  assert.equal(inactive.allowed, false, 'inactive → denied (the route never reaches issue())');
+  const belowFloor = access.decideSourceAccess({ rank: 'xenos', status: 'active', floor: 'metic', scopeKeys: ['dev-box'], moduleScopeMap: scopeMap });
+  assert.equal(belowFloor.allowed, false, 'below floor → denied (no credential path)');
+});
+
+console.log(`\nbox_credential.mjs: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/box_host_keys.mjs

@@ -99,4 +99,28 @@ const RSA = 'ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC/FqVQUVRAmcDHRBeEZZwuW0xgsAP
   assert.equal(r.error, 'expect_type_and_key_only');
 }
 
+// 11) hostKeysAreStale (task 1002509) — a rebuild mints fresh host keys, and the row
+// keeps the OLD ones until the new box re-reports. Serving those is the "Host denied
+// (verification failed)" lockout, so a report that predates the current droplet's
+// activation must be refused and the client must keyscan instead.
+{
+  const { hostKeysAreStale } = require('../modules/dev-box/boxes.js');
+  assert.equal(
+    hostKeysAreStale({ hostKeysAt: '2026-07-01T08:00:00Z', activeSince: '2026-07-01T09:00:00Z' }),
+    true,
+    'a report older than the activation describes a box that no longer exists'
+  );
+  assert.equal(
+    hostKeysAreStale({ hostKeysAt: '2026-07-01T10:00:00Z', activeSince: '2026-07-01T09:00:00Z' }),
+    false,
+    'a report from after this box came up is the live identity'
+  );
+  assert.equal(hostKeysAreStale({ hostKeysAt: null, activeSince: '2026-07-01T09:00:00Z' }), true);
+  assert.equal(hostKeysAreStale({ hostKeysAt: '2026-07-01T10:00:00Z', activeSince: null }), true);
+  assert.equal(hostKeysAreStale({}), true, 'no evidence of freshness → not fresh');
+  assert.equal(hostKeysAreStale({ hostKeysAt: 'garbage', activeSince: '2026-07-01T09:00:00Z' }), true);
+  const t = new Date('2026-07-01T09:00:00Z');
+  assert.equal(hostKeysAreStale({ hostKeysAt: t, activeSince: t }), false, 'Date objects, equal instant → fresh');
+}
+
 console.log('box_host_keys: all assertions passed');

package/tests/box_infra_resolve.mjs

@@ -0,0 +1,149 @@
+// tests/box_infra_resolve.mjs
+//
+// R98 (goal 1000051/1000052, ADR 0150) — box.js locates the box cloud-init from
+// the INSTANCE root (not the vendored @bongos/core package) and FAILS LOUD when it
+// cannot, so a box can never be provisioned with empty user-data (= a bare box that
+// boots with no clone, no toolchain, no terminal).
+//
+// Pure + hermetic: boxInfraCandidates takes injected {env, repoRoot}; readCloudInit
+// takes an explicit infraDir. Temp dirs stand in for a real infra/ tree. NO DB, NO
+// network, NO droplet — requiring box.js does not run main() (require.main guard)
+// and loadDeps() (the DB layer) is only reached inside main().
+//
+// Run:  node tests/box_infra_resolve.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const box = require('../scripts/gds/box.js');
+
+const { test, summary } = makeRunner();
+
+// The 9 scripts readCloudInit gz+b64-inlines into the cloud-init — missing ANY of
+// them half-wires the box. Kept in sync with box.js's fileGzB64 calls.
+const INLINED = [
+  'box-source-fetch.sh', 'box-authorized-keys-fetch.sh', 'box-terminal.service',
+  'box-terminal-credsync.service', 'box-terminal-credential.path', 'cloudflared.service',
+  'cloudflared-run.sh', 'close-box.sh', 'otb-box-launch.sh',
+];
+const TEMPLATE = box.BOX_INFRA_TEMPLATE; // 'builder-box-cloud-init.yaml'
+
+// A minimal template exercising a few of the substitution tokens (readCloudInit
+// still calls fileGzB64 for ALL 9 inlined files regardless, so the happy path must
+// provide every one).
+const TEMPLATE_BODY = [
+  '#cloud-config',
+  'write_files:',
+  '  - path: /opt/box-source-fetch.sh',
+  '    encoding: gz+b64',
+  '    content: __BOX_SOURCE_FETCH_B64__',
+  '  - path: /opt/cloudflared-run.sh',
+  '    encoding: gz+b64',
+  '    content: __CLOUDFLARED_RUN_B64__',
+  'runcmd:',
+  '  - git clone __REPO_URL__ /workspace',
+  '',
+].join('\n');
+
+const tmps = [];
+function tmpdir() {
+  const d = fs.mkdtempSync(path.join(os.tmpdir(), 'boxinfra-'));
+  tmps.push(d);
+  return d;
+}
+// Build an infra/ dir; choose whether the template + which inlined files exist.
+function makeInfra({ template = true, inlined = INLINED } = {}) {
+  const root = tmpdir();
+  const infra = path.join(root, 'infra');
+  fs.mkdirSync(infra, { recursive: true });
+  if (template) fs.writeFileSync(path.join(infra, TEMPLATE), TEMPLATE_BODY);
+  for (const f of inlined) fs.writeFileSync(path.join(infra, f), `# ${f}\n`);
+  return { root, infra };
+}
+
+// ===========================================================================
+// boxInfraCandidates — ordering (pure, injected; ADR 0150 prong A)
+// ===========================================================================
+await test('candidate order: override → explicit instance root → repoRoot → node_modules walk-up', () => {
+  const env = { CLOUDBONGOS_BOX_INFRA_DIR: '/ovr', CLOUDBONGOS_INSTANCE_ROOT: '/inst' };
+  const c = box.boxInfraCandidates({ env, repoRoot: '/srv/app/node_modules/@bongos/core' });
+  assert.equal(c[0], path.resolve('/ovr'), 'explicit override is first');
+  assert.equal(c[1], path.join('/inst', 'infra'), 'then the explicit instance root');
+  assert.equal(c[2], '/srv/app/node_modules/@bongos/core/infra', 'then REPO_ROOT/infra');
+  // the load-bearing case: a vendored core walks UP out of node_modules to its host
+  // instance root, so infra/ is found with no pointer at all.
+  assert.ok(c.includes('/srv/app/infra'), 'walk-up recovers the host instance root infra/');
+});
+
+await test('repoRoot/infra precedes its ancestors in the walk-up (robust to any cwd pointer)', () => {
+  const c = box.boxInfraCandidates({ env: {}, repoRoot: '/x/y/z' });
+  const i0 = c.indexOf('/x/y/z/infra');
+  const i1 = c.indexOf('/x/y/infra');
+  const i2 = c.indexOf('/x/infra');
+  assert.ok(i0 >= 0 && i1 > i0 && i2 > i1, 'repoRoot/infra, then /x/y/infra, then /x/infra — in order');
+});
+
+// ===========================================================================
+// resolveBoxInfraDir — picks the FIRST candidate that actually holds the template
+// ===========================================================================
+await test('resolveBoxInfraDir picks the override dir when it holds the template', () => {
+  const { infra } = makeInfra();
+  const got = box.resolveBoxInfraDir({ env: { CLOUDBONGOS_BOX_INFRA_DIR: infra }, repoRoot: '/nope/does/not/exist' });
+  assert.equal(got, infra);
+});
+
+await test('resolveBoxInfraDir falls THROUGH a template-less override to the instance-root infra/', () => {
+  const emptyOverride = path.join(tmpdir(), 'infra');
+  fs.mkdirSync(emptyOverride, { recursive: true }); // exists, but no template inside
+  const { infra } = makeInfra();                    // a real infra/ to fall through to
+  const instRoot = path.dirname(infra);             // <root>, so <root>/infra === the real one
+  const got = box.resolveBoxInfraDir({
+    env: { CLOUDBONGOS_BOX_INFRA_DIR: emptyOverride, CLOUDBONGOS_INSTANCE_ROOT: instRoot },
+    repoRoot: '/nope',
+  });
+  assert.equal(got, infra, 'skips the template-less override, takes the instance-root infra/');
+});
+
+await test('resolveBoxInfraDir → null when NO candidate holds the template', () => {
+  const bare = tmpdir(); // a dir tree with no infra/ anywhere
+  const got = box.resolveBoxInfraDir({ env: {}, repoRoot: path.join(bare, 'node_modules', '@bongos', 'core') });
+  assert.equal(got, null);
+});
+
+// ===========================================================================
+// readCloudInit — FAIL LOUD (ADR 0150 prong B): never return null / empty
+// ===========================================================================
+await test('readCloudInit THROWS when infra cannot be located (never returns null)', () => {
+  assert.throws(
+    () => box.readCloudInit({ infraDir: null }),
+    /not found|boot bare|ADR 0150/i,
+  );
+});
+
+await test('readCloudInit THROWS when infra is INCOMPLETE (an inlined script is missing)', () => {
+  const { infra } = makeInfra({ inlined: INLINED.filter((f) => f !== 'cloudflared-run.sh') });
+  assert.throws(
+    () => box.readCloudInit({ infraDir: infra }),
+    /incomplete|cloudflared-run\.sh|ADR 0150/i,
+  );
+});
+
+// ===========================================================================
+// readCloudInit — happy path: renders non-empty + every placeholder substituted
+// ===========================================================================
+await test('readCloudInit renders a non-empty cloud-init with no leftover __PLACEHOLDER__ tokens', () => {
+  const { infra } = makeInfra();
+  const out = box.readCloudInit({
+    infraDir: infra, authorizedKeysBlock: 'ssh-ed25519 AAAA', boxEnv: 'X=1', gdsSession: '{"t":1}',
+  });
+  assert.ok(out && out.length > 0, 'renders a non-empty cloud-init');
+  assert.ok(!/__[A-Z0-9_]+__/.test(out), 'no unsubstituted __PLACEHOLDER__ tokens remain');
+});
+
+for (const d of tmps) { try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* best-effort */ } }
+summary();

package/tests/box_scope_session.mjs

@@ -45,11 +45,15 @@ const t = async (name, fn) => {
 };
 
 // ---- allowBoxScope middleware ------------------------------------------------
-await t('allowBoxScope sets req.allowBoxScope = true and calls next()', async () => {
+// BV1.R99: the opt-in is no longer a bare boolean flag — it DECLARES the box
+// scope's own permission allow-list, and requireBuilder checks the declaration
+// against the registry. The reachability contract below is unchanged.
+await t('allowBoxScope declares the box scope\'s allow-list and calls next()', async () => {
   const req = {};
   let nexted = false;
   auth.allowBoxScope(req, fakeRes(), () => { nexted = true; });
-  assert.equal(req.allowBoxScope, true);
+  assert.deepEqual([...req.sessionScopeNeeds], [...auth.sessionScopeFor('box').permissions]);
+  assert.ok(req.sessionScopeNeeds.length > 0, 'an empty declaration would deny every box route');
   assert.equal(nexted, true);
 });
 

package/tests/box_sync.mjs

@@ -0,0 +1,55 @@
+// tests/box_sync.mjs
+//
+// BV1.R96 (goal 1000051) — "sync now": box-sync.js locates the box source-fetch
+// script (so re-running it re-scopes the box to the active claim) and degrades
+// cleanly off a box. Pure + hermetic: resolveFetchScript threads {env, repoRoot}
+// to the shared resolveBoxInfraDir (ADR 0150 / R98); temp dirs stand in for a real
+// box infra/ tree. NO DB, NO network, NO box.
+//
+// Run:  node tests/box_sync.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const boxSync = require('../scripts/gds/box-sync.js');
+
+const { test, summary } = makeRunner();
+
+const tmps = [];
+function makeInfra({ template = true, fetch = true } = {}) {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'boxsync-'));
+  tmps.push(root);
+  const infra = path.join(root, 'infra');
+  fs.mkdirSync(infra, { recursive: true });
+  // resolveBoxInfraDir validates an infra/ by the presence of the cloud-init template.
+  if (template) fs.writeFileSync(path.join(infra, 'builder-box-cloud-init.yaml'), '#cloud-config\n');
+  if (fetch) fs.writeFileSync(path.join(infra, boxSync.FETCH_SCRIPT), '#!/usr/bin/env bash\necho fetch\n');
+  return { root, infra };
+}
+
+await test('resolves the box source-fetch script when it is present on the box', () => {
+  const { infra } = makeInfra();
+  const got = boxSync.resolveFetchScript({ env: { CLOUDBONGOS_BOX_INFRA_DIR: infra }, repoRoot: '/nope' });
+  assert.equal(got, path.join(infra, boxSync.FETCH_SCRIPT));
+});
+
+await test('→ null when the infra/ has no source-fetch script (template present, fetch absent)', () => {
+  const { infra } = makeInfra({ fetch: false });
+  const got = boxSync.resolveFetchScript({ env: { CLOUDBONGOS_BOX_INFRA_DIR: infra }, repoRoot: '/nope' });
+  assert.equal(got, null);
+});
+
+await test('→ null when there is no infra/ at all (i.e. NOT on a box)', () => {
+  const bare = fs.mkdtempSync(path.join(os.tmpdir(), 'boxsync-bare-'));
+  tmps.push(bare);
+  const got = boxSync.resolveFetchScript({ env: {}, repoRoot: path.join(bare, 'node_modules', '@bongos', 'core') });
+  assert.equal(got, null);
+});
+
+for (const d of tmps) { try { fs.rmSync(d, { recursive: true, force: true }); } catch { /* best-effort */ } }
+summary();

package/tests/box_task_scope.mjs

@@ -0,0 +1,99 @@
+// tests/box_task_scope.mjs
+//
+// R95 (goal 1000051, ADR 0148) — the end-to-end PURE decision for task-scoped
+// source access, composing the two halves shipped in R92 + R93:
+//   lifecycle.moduleScopeForActiveClaims (claims → tasks → goals.scope_modules)
+//     → box-access.decideSourceAccess({ scopeKeys, moduleScopeMap })
+// Proves R95's done-when as named behavior: 0 active claims → BASE-only; N active
+// claims → BASE ∪ the union of ALL N goals' module scopes.
+//
+// DB-free: moduleScopeForActiveClaims honours the #538 deps.pool seam
+// (NODE_ENV==='test'), so a SQL-aware fake pool stands in for Postgres — we hand it
+// the rows the DISTINCT-union query would return (the union itself is Postgres's
+// job, shape-proven in module_scope_active_claims.mjs) and assert the WHOLE chain
+// down to the sparse-checkout paths. The real module-scope-map (a pure core module)
+// is the map the route passes in.
+//
+// Run:  node tests/box_task_scope.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner, makeSqlAwareClient } from './helpers.mjs';
+
+process.env.NODE_ENV = 'test';
+
+const require = createRequire(import.meta.url);
+const db = require('../modules/lifecycle/db.js');
+const access = require('../modules/dev-box/box-access.js');
+const scopeMap = require('../src/bongos/module-scope-map.js');
+
+const { test, summary } = makeRunner();
+const BASE = access.BASE_SPARSE_PATHS;
+
+// Fake pool: the resolver issues ONE query (claims→tasks→goals, unnest
+// scope_modules); return the module-key rows a builder's active claims would
+// produce (already DISTINCT-unioned + ORDER BY m, as Postgres would).
+function poolReturning(moduleKeyRows) {
+  const c = makeSqlAwareClient((s) =>
+    (/FROM claims c/.test(s) && /unnest\(g\.scope_modules\)/.test(s)) ? { rows: moduleKeyRows } : null);
+  return { query: (sql, params) => c._client.query(sql, params), connect: c.connect, queries: c._client.queries };
+}
+
+// The full chain a box-fetch runs: resolve the active-claim scope, then decide the
+// source spec from it (rank still gates ALLOW/DENY).
+async function specForClaims({ builderId = 3, rank = 'metic', status = 'active', moduleKeyRows }) {
+  const pool = poolReturning(moduleKeyRows);
+  const scopeKeys = await db.moduleScopeForActiveClaims(builderId, { pool });
+  return { scopeKeys, decision: access.decideSourceAccess({ rank, status, scopeKeys, moduleScopeMap: scopeMap }) };
+}
+
+// =========================================================================
+// 0 active claims → BASE-only (the pre-existing Bongos instance, nothing extra)
+// =========================================================================
+await test('0 active claims → base-only spec', async () => {
+  const { scopeKeys, decision } = await specForClaims({ moduleKeyRows: [] });
+  assert.deepEqual(scopeKeys, [], 'no active claim → no scope keys');
+  assert.equal(decision.allowed, true);
+  assert.equal(decision.scope, 'base');
+  assert.deepEqual(decision.spec.sparsePaths, [...BASE], 'the box carries only BASE');
+});
+
+// =========================================================================
+// N active claims across goals → BASE ∪ the UNION of all N goals' scopes
+// =========================================================================
+await test('N active claims → base ∪ the union of all their goals’ module scopes', async () => {
+  // Two claims: goal A scoped {dev-box, status-ui}, goal B scoped {hall-ui}.
+  // Postgres DISTINCT-unions + ORDER BY m to this key set:
+  const { scopeKeys, decision } = await specForClaims({
+    moduleKeyRows: [{ module_key: 'dev-box' }, { module_key: 'hall-ui' }, { module_key: 'status-ui' }],
+  });
+  assert.deepEqual(scopeKeys, ['dev-box', 'hall-ui', 'status-ui'], 'union across the active claims');
+  assert.equal(decision.scope, 'task');
+  // BASE ∪ each module's DIRECTORY globs (dev-box's box-CLI FILE globs cone-filtered out).
+  assert.deepEqual(
+    decision.spec.sparsePaths,
+    [...BASE, 'devbox-app', 'modules/dev-box', 'modules/hall-ui', 'modules/status-ui'],
+    'every claimed goal’s module dirs are materialized, deduped + sorted',
+  );
+  assert.ok(!decision.spec.sparsePaths.includes('scripts/gds/box.js'), 'file globs never enter the sparse set');
+});
+
+// =========================================================================
+// One claim, one goal → BASE ∪ that goal's scope (the single-claim base case)
+// =========================================================================
+await test('a single claim → base ∪ that one goal’s module scope', async () => {
+  const { decision } = await specForClaims({ moduleKeyRows: [{ module_key: 'status-ui' }] });
+  assert.equal(decision.scope, 'task');
+  assert.deepEqual(decision.spec.sparsePaths, [...BASE, 'modules/status-ui']);
+});
+
+// =========================================================================
+// Rank/status STILL gate ALLOW/DENY ahead of any task scope (ADR 0148 C4 posture)
+// =========================================================================
+await test('an inactive builder is denied even with claims in scope', async () => {
+  const inactive = await specForClaims({ status: 'inactive', moduleKeyRows: [{ module_key: 'dev-box' }] });
+  assert.equal(inactive.decision.allowed, false);
+  assert.equal(inactive.decision.reason, 'BUILDER_INACTIVE');
+});
+
+summary();