@bongos/core 1.18.3 → 1.18.18

package/tests/backup_cli.mjs

@@ -10,6 +10,7 @@
 // Run:  node tests/backup_cli.mjs
 
 import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
 
 let passed = 0;
 let failed = 0;
@@ -94,6 +95,59 @@ t('trigger response: 409 when already running', () => {
   assert.equal(response.error, 'backup_already_running');
 });
 
+// ---- staleness detection (task 1002479) -------------------------------------
+// These import the REAL implementations rather than re-implementing them, so a
+// regression in the shipped code fails here instead of passing against a copy.
+const backupRoute = createRequire(import.meta.url)('../src/bongos/routes/backup.js');
+const { parseDumpTimestamp, dumpAgeHours, isStaleDump } = backupRoute;
+
+const NOW = Date.parse('2026-07-28T23:00:00Z');
+
+t('parseDumpTimestamp: the dump stamp is NOT plain ISO — colons must be reinserted', () => {
+  // Regression guard: Date.parse on the raw stamp returns NaN. If someone
+  // "simplifies" this to Date.parse(stamp), staleness silently becomes unknown
+  // → every dump reads stale (or, with a sloppier fallback, every dump reads fresh).
+  assert.ok(Number.isNaN(Date.parse('2026-07-28T230421Z')), 'raw stamp should not parse as ISO');
+  assert.equal(parseDumpTimestamp('2026-07-28T230421Z'), Date.parse('2026-07-28T23:04:21Z'));
+});
+
+t('parseDumpTimestamp: rejects garbage rather than guessing', () => {
+  for (const bad of ['', null, undefined, 'nope', '2026-07-28', '2026-07-28T2304Z']) {
+    assert.equal(parseDumpTimestamp(bad), null, `should reject ${JSON.stringify(bad)}`);
+  }
+});
+
+t('dumpAgeHours: computes hours, floors at 0 for a future stamp', () => {
+  assert.equal(dumpAgeHours('2026-07-28T220000Z', NOW), 1);
+  assert.equal(dumpAgeHours('2026-07-27T230000Z', NOW), 24);
+  assert.equal(dumpAgeHours('2026-07-29T230000Z', NOW), 0, 'future stamp must not go negative');
+  assert.equal(dumpAgeHours('garbage', NOW), null);
+});
+
+t('isStaleDump: fresh dump is not stale', () => {
+  assert.equal(isStaleDump('2026-07-28T230421Z', NOW), false);
+  assert.equal(isStaleDump('2026-07-27T140000Z', NOW), false, '33h is inside the 36h threshold');
+});
+
+t('isStaleDump: the real 13-day cloudbongos outage is detected', () => {
+  // The actual last good dump before the 203/EXEC failure was 2026-07-15.
+  assert.equal(isStaleDump('2026-07-15T040302Z', NOW), true);
+  assert.ok(dumpAgeHours('2026-07-15T040302Z', NOW) > 300, 'should be ~13 days of hours');
+});
+
+t('isStaleDump: an undateable stamp fails LOUD (stale), never silently healthy', () => {
+  assert.equal(isStaleDump('garbage', NOW), true);
+  assert.equal(isStaleDump('', NOW), true);
+  assert.equal(isStaleDump(undefined, NOW), true);
+});
+
+t('isStaleDump: threshold boundary is exclusive', () => {
+  const at36h = '2026-07-27T110000Z'; // exactly 36h before NOW
+  assert.equal(dumpAgeHours(at36h, NOW), 36);
+  assert.equal(isStaleDump(at36h, NOW, 36), false, 'exactly at threshold is not yet stale');
+  assert.equal(isStaleDump('2026-07-27T105900Z', NOW, 36), true, 'one minute past is stale');
+});
+
 // ---- summary ----------------------------------------------------------------
 console.log('');
 if (failed === 0) {

package/tests/bongos_box_connect.mjs

@@ -3,6 +3,7 @@
 // helpers are exercised. Picked up by scripts/gds/run-unit-tests.js (the `unit` gate).
 import assert from 'node:assert/strict';
 import { test } from 'node:test';
+import crypto from 'node:crypto';
 import lib from '../scripts/gds/box-connect-lib.js';
 
 const HOST = 'box-alice.dev.amazonprimea.com';
@@ -63,6 +64,62 @@ test('buildKnownHostsUpsert drops the stale line for the host, keeps others, app
   assert.ok(next.includes(`${HOST} ssh-rsa AAAARSANEW`), 'appends every reported key');
 });
 
+// task 1002509 — the upsert used to compare field 1 to the hostname with `!==`, so
+// the two forms OpenSSH actually writes survived the "replace" and stale lines
+// ACCUMULATED: the client kept verifying against the first, now-wrong entry
+// ("Host denied (verification failed)") on a box that had just re-reported keys.
+test('buildKnownHostsUpsert drops a host,ip entry for this box (the accumulation bug)', () => {
+  const existing = `${HOST},64.225.49.206 ssh-ed25519 STALE\n`;
+  const next = lib.buildKnownHostsUpsert(existing, HOST, 'ssh-ed25519 AAAANEW');
+  assert.ok(!next.includes('STALE'), 'a `host,ip` field-1 names this host and must be replaced');
+  assert.ok(next.includes(`${HOST} ssh-ed25519 AAAANEW`));
+});
+
+test('buildKnownHostsUpsert drops a HASHED entry for this box, keeps another host, keeps comments', () => {
+  const salt = crypto.randomBytes(20);
+  const hashFor = (h) => `|1|${salt.toString('base64')}|${crypto.createHmac('sha1', salt).update(h).digest('base64')}`;
+  const existing = [
+    '# hand-written note',
+    `${hashFor(HOST)} ssh-ed25519 STALEHASHED`,
+    `${hashFor('other.example.com')} ssh-ed25519 KEEPHASHED`,
+  ].join('\n') + '\n';
+  const next = lib.buildKnownHostsUpsert(existing, HOST, 'ssh-ed25519 AAAANEW');
+  assert.ok(!next.includes('STALEHASHED'), 'HashKnownHosts entries must be matched, not stepped over');
+  assert.ok(next.includes('KEEPHASHED'), 'another host hashed with the same salt stays');
+  assert.ok(next.includes('# hand-written note'), 'comments survive');
+});
+
+test('buildKnownHostsUpsert drops an IP-keyed line when the box IP is supplied', () => {
+  const existing = '203.0.113.7 ssh-ed25519 STALEIP\nunrelated.example.com ssh-ed25519 KEEP\n';
+  const next = lib.buildKnownHostsUpsert(existing, HOST, 'ssh-ed25519 AAAANEW', '203.0.113.7');
+  assert.ok(!next.includes('STALEIP'), 'DNS is repointed on every wake — an old IP line is stale too');
+  assert.ok(next.includes('KEEP'));
+});
+
+test('buildKnownHostsUpsert is idempotent — re-running never grows the file', () => {
+  const first = lib.buildKnownHostsUpsert('', HOST, 'ssh-ed25519 AAAANEW\nssh-rsa AAAARSA');
+  const second = lib.buildKnownHostsUpsert(first, HOST, 'ssh-ed25519 AAAANEW\nssh-rsa AAAARSA');
+  assert.equal(second, first);
+  assert.equal(second.split('\n').filter(Boolean).length, 2);
+});
+
+// task 1002509 — the old inline logic FAILED OPEN: no fingerprint (ssh-keygen absent
+// from a GUI process's leaner PATH) or an unreadable key list meant "skip", so a
+// builder whose key was never on the server got a bare "Permission denied". A
+// redundant POST is free (the server upserts by fingerprint), uncertainty is not.
+test('decideKeyRegistration registers on uncertainty and skips only on proof', () => {
+  const FP = 'SHA256:abc';
+  assert.deepEqual(lib.decideKeyRegistration({ created: true }), { register: true, why: 'created' });
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listedKeys: [{ fingerprint: FP }] }).register, false);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listedKeys: [{ fingerprint: 'SHA256:other' }] }).register, true);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listedKeys: [] }).register, true);
+  // the two fail-open holes this closes:
+  assert.equal(lib.decideKeyRegistration({ fingerprint: null, listedKeys: [] }).register, true);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: null, listedKeys: [{ fingerprint: FP }] }).register, true);
+  assert.equal(lib.decideKeyRegistration({ fingerprint: FP, listFailed: true }).register, true);
+  assert.equal(lib.decideKeyRegistration({}).register, true, 'no information at all → register');
+});
+
 test('buildRemoteShellCommand forces claude only on first run and always lands in /workspace', () => {
   const first = lib.buildRemoteShellCommand({ firstRun: true });
   const later = lib.buildRemoteShellCommand({ firstRun: false });
@@ -74,6 +131,26 @@ test('buildRemoteShellCommand forces claude only on first run and always lands i
   assert.match(later, /exec bash -l/);
 });
 
+test('buildRemoteShellCommand re-scopes on connect ONLY with sync:true (BV1.R101)', () => {
+  const noSync = lib.buildRemoteShellCommand({ firstRun: false, sync: false });
+  const withSync = lib.buildRemoteShellCommand({ firstRun: false, sync: true });
+  assert.ok(!/box-sync/.test(noSync), 'default (sync:false) never re-scopes');
+  assert.match(withSync, /node scripts\/gds\/box-sync\.js \|\| true/);
+  // order: cd → re-scope → shell, so the builder lands in the scoped folder.
+  assert.ok(withSync.indexOf('cd /workspace') < withSync.indexOf('box-sync'), 'cd before sync');
+  assert.ok(withSync.indexOf('box-sync') < withSync.indexOf('exec bash -l'), 'sync before the shell');
+  // sync + firstRun: re-scope THEN the one-time claude /login handoff.
+  const both = lib.buildRemoteShellCommand({ firstRun: true, sync: true });
+  assert.ok(both.indexOf('box-sync') < both.indexOf('claude || true'), 'sync before the first-run login');
+});
+
+test('buildRemoteResyncCommand is a cd + re-scope one-shot (bongos code path) — no shell (BV1.R101)', () => {
+  const cmd = lib.buildRemoteResyncCommand();
+  assert.match(cmd, /cd \/workspace/);
+  assert.match(cmd, /node scripts\/gds\/box-sync\.js \|\| true/);
+  assert.ok(!/exec bash/.test(cmd), 'one-shot — never spawns a login shell');
+});
+
 test('remoteAuthority builds a VS Code Remote-SSH authority', () => {
   assert.equal(lib.remoteAuthority(HOST), `ssh-remote+${HOST}`);
 });

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