@bongos/core 1.17.0

package/tests/bongos_downloads.mjs

@@ -0,0 +1,118 @@
+// tests/bongos_downloads.mjs
+//
+// Hermetic unit tests for the standalone `bongos` CLI download redirects
+// (task 1248, V4.R81) — src/bongos-downloads.js — plus a shape check that the
+// COMMITTED config/bongos-cli.json actually parses and resolves (so a bad release
+// bump fails this gate, not prod). Pure: no server, no network.
+//
+// Run:  node tests/bongos_downloads.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { buildBongosDownloads } = require('../src/bongos-downloads.js');
+const committedConfig = require('../config/bongos-cli.json');
+
+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 CFG = {
+  releases_repo: 'lars589/amazonprimea-bongos',
+  version: '1.2.3',
+  assets: {
+    'mac-arm64': 'bongos-1.2.3-darwin-arm64',
+    'linux-x64': 'bongos-1.2.3-linux-x64',
+    'win-x64': 'bongos-1.2.3-windows-x64.exe',
+  },
+  aliases: { mac: 'mac-arm64', linux: 'linux-x64', win: 'win-x64' },
+};
+
+console.log('redirectFor:');
+
+t('maps a known target to the versioned release-asset URL', () => {
+  const d = buildBongosDownloads(CFG);
+  assert.equal(
+    d.redirectFor('mac-arm64'),
+    'https://github.com/lars589/amazonprimea-bongos/releases/download/v1.2.3/bongos-1.2.3-darwin-arm64'
+  );
+});
+
+t('aliases resolve; case and a stray .exe are tolerated', () => {
+  const d = buildBongosDownloads(CFG);
+  assert.equal(d.redirectFor('mac'), d.redirectFor('mac-arm64'));
+  assert.equal(d.redirectFor('WIN'), d.redirectFor('win-x64'));
+  assert.equal(d.redirectFor('win-x64.exe'), d.redirectFor('win-x64'));
+});
+
+t('unknown targets, junk, and prototype-pollution probes → null', () => {
+  const d = buildBongosDownloads(CFG);
+  assert.equal(d.redirectFor('freebsd-riscv'), null);
+  assert.equal(d.redirectFor('../../etc/passwd'), null);
+  assert.equal(d.redirectFor('constructor'), null);
+  assert.equal(d.redirectFor('__proto__'), null);
+  assert.equal(d.redirectFor(''), null);
+  assert.equal(d.redirectFor('x'.repeat(50)), null);
+  assert.equal(d.redirectFor(null), null);
+});
+
+t('asset filenames are URL-encoded into the redirect (no path breakout)', () => {
+  const d = buildBongosDownloads({
+    ...CFG,
+    assets: { 'mac-arm64': 'evil/../name' },
+  });
+  assert.ok(d.redirectFor('mac-arm64').endsWith('/v1.2.3/evil%2F..%2Fname'));
+});
+
+console.log('latestJson / versionJson:');
+
+t('latestJson lists every target with file + url', () => {
+  const d = buildBongosDownloads(CFG);
+  const j = d.latestJson();
+  assert.equal(j.version, '1.2.3');
+  assert.deepEqual(Object.keys(j.assets).sort(), ['linux-x64', 'mac-arm64', 'win-x64']);
+  assert.equal(j.assets['win-x64'].file, 'bongos-1.2.3-windows-x64.exe');
+  assert.ok(j.assets['win-x64'].url.includes('/releases/download/v1.2.3/'));
+});
+
+t('versionJson is the flat {version, assets:{target:url}} form', () => {
+  const d = buildBongosDownloads(CFG);
+  const v = d.versionJson();
+  assert.equal(v.version, '1.2.3');
+  assert.equal(typeof v.assets['mac-arm64'], 'string');
+  assert.equal(v.assets['linux-x64'], d.redirectFor('linux-x64'));
+});
+
+console.log('config validation:');
+
+t('bad repo or version is rejected at boot, not served', () => {
+  assert.throws(() => buildBongosDownloads({ ...CFG, releases_repo: 'no-slash' }));
+  assert.throws(() => buildBongosDownloads({ ...CFG, releases_repo: 'a/b/c' }));
+  assert.throws(() => buildBongosDownloads({ ...CFG, version: 'v1.2.3' }));
+  assert.throws(() => buildBongosDownloads(null));
+});
+
+console.log('committed config:');
+
+t('config/bongos-cli.json parses, resolves every target, and aliases point at real targets', () => {
+  const d = buildBongosDownloads(committedConfig);
+  const j = d.latestJson();
+  for (const target of Object.keys(committedConfig.assets)) {
+    assert.ok(d.redirectFor(target), `target ${target} must resolve`);
+    assert.ok(j.assets[target].url.startsWith('https://github.com/'), `url for ${target}`);
+  }
+  for (const [alias, target] of Object.entries(committedConfig.aliases || {})) {
+    assert.equal(d.redirectFor(alias), d.redirectFor(target), `alias ${alias} → ${target}`);
+  }
+  // Every asset filename embeds the config version — catches a half-bumped release.
+  for (const file of Object.values(committedConfig.assets)) {
+    assert.ok(file.includes(committedConfig.version), `${file} should carry version ${committedConfig.version}`);
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/bongos_login.mjs

@@ -0,0 +1,34 @@
+// tests/bongos_login.mjs — pure helpers behind `bongos login <instance>`
+// (V4.R83 / task 1250). DB-free + network-free. Picked up by run-unit-tests.js.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { normalizeInstanceBase, pollDecision } = require('../scripts/gds/login.js');
+
+test('normalizeInstanceBase adds https, strips trailing slashes + a pasted /api/gds', () => {
+  assert.equal(normalizeInstanceBase('amazonprimea.com'), 'https://amazonprimea.com');
+  assert.equal(normalizeInstanceBase('https://amazonprimea.com/'), 'https://amazonprimea.com');
+  assert.equal(normalizeInstanceBase('https://amazonprimea.com///'), 'https://amazonprimea.com');
+  assert.equal(normalizeInstanceBase('https://amazonprimea.com/api/gds'), 'https://amazonprimea.com');
+  assert.equal(normalizeInstanceBase('https://amazonprimea.com/api/gds/'), 'https://amazonprimea.com');
+  assert.equal(normalizeInstanceBase('http://localhost:3000'), 'http://localhost:3000');
+});
+
+test('normalizeInstanceBase throws on empty', () => {
+  assert.throws(() => normalizeInstanceBase(''));
+  assert.throws(() => normalizeInstanceBase('   '));
+  assert.throws(() => normalizeInstanceBase(null));
+});
+
+test('pollDecision maps the /access-requests/status body to a loop action', () => {
+  assert.equal(pollDecision({ admitted: true, status: 'invited' }), 'admitted');
+  assert.equal(pollDecision({ status: 'invited' }), 'admitted');
+  assert.equal(pollDecision({ status: 'member', admitted: true }), 'admitted');
+  assert.equal(pollDecision({ status: 'dismissed' }), 'dismissed');
+  assert.equal(pollDecision({ status: 'pending', admitted: false }), 'wait');
+  assert.equal(pollDecision({ status: 'none' }), 'wait');
+  assert.equal(pollDecision(null), 'wait');
+  assert.equal(pollDecision({}), 'wait');
+});

package/tests/box_access.mjs

@@ -0,0 +1,186 @@
+// tests/box_access.mjs
+//
+// Hermetic unit smoke for the rank-gated SOURCE-access decision core of
+// modules/dev-box/box-access.js (ADR 0031 §6 + §9.2, task #600; extended for the
+// sandbox-for-everyone starter scope, ADR 0052 / #1001). Covers the PURE
+// functions the GET /box/source-access route and `box.js reconcile` both consume
+// — with NO database, NO DigitalOcean, NO network. The DB helpers
+// (listBoxesForReconcile / recordSourceEvent / flagBoxReconcileForBuilder) are
+// thin wrappers exercised on the control plane; the DECISIONS they rely on are
+// pinned here so the route and the reconciler can never drift from one rule.
+//
+// Re-added under #674 (the test was written + passing in #600 but deferred by
+// parallel-claim conflicts on tests/ and docs/file-map.md). Wired into
+// scripts/gds/smoke-box.sh step 1b.
+//
+// Run:  node tests/box_access.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const access = require('../modules/dev-box/box-access.js');
+const boxes = require('../modules/dev-box/boxes.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 FLOOR = boxes.DEFAULT_PROVISION_FLOOR; // 'xenos' — everyone meets the default
+
+console.log('boxCanHoldSource — only a live/becoming-live droplet holds a clone:');
+
+t('boxCanHoldSource: true for active / provisioning / waking', () => {
+  assert.equal(access.boxCanHoldSource('active'), true);
+  assert.equal(access.boxCanHoldSource('provisioning'), true);
+  assert.equal(access.boxCanHoldSource('waking'), true);
+});
+
+t('boxCanHoldSource: false for parked / destroyed / none / idle / unknown', () => {
+  assert.equal(access.boxCanHoldSource('parked'), false);
+  assert.equal(access.boxCanHoldSource('destroyed'), false);
+  assert.equal(access.boxCanHoldSource('none'), false);
+  assert.equal(access.boxCanHoldSource('idle'), false);
+  assert.equal(access.boxCanHoldSource(undefined), false);
+});
+
+console.log('\ncloneSpecForScope — full vs starter, fail-closed to least privilege:');
+
+t("cloneSpecForScope('full') → full clone, no sparse paths", () => {
+  assert.deepEqual(access.cloneSpecForScope('full'), { scope: 'full', mode: 'full', sparsePaths: null });
+});
+
+t("cloneSpecForScope('starter') → sparse clone of the starter surface", () => {
+  const spec = access.cloneSpecForScope('starter');
+  assert.equal(spec.scope, 'starter');
+  assert.equal(spec.mode, 'sparse');
+  assert.deepEqual(spec.sparsePaths, access.STARTER_SPARSE_PATHS);
+});
+
+t('cloneSpecForScope: unknown/missing scope FAILS CLOSED to starter (never full)', () => {
+  for (const bad of ['admin', '', undefined, null, 'FULL']) {
+    assert.equal(access.cloneSpecForScope(bad).scope, 'starter', `scope ${JSON.stringify(bad)} must collapse to starter`);
+  }
+});
+
+t('cloneSpecForScope: starter sparsePaths is a COPY (mutating it cannot poison the catalog)', () => {
+  const spec = access.cloneSpecForScope('starter');
+  spec.sparsePaths.push('SHOULD_NOT_PERSIST');
+  assert.ok(!access.STARTER_SPARSE_PATHS.includes('SHOULD_NOT_PERSIST'),
+    'the returned sparsePaths must not alias the shared STARTER_SPARSE_PATHS array');
+});
+
+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']) {
+    assert.ok(access.STARTER_SPARSE_PATHS.includes(p), `starter scope must include ${p}`);
+  }
+});
+
+t('starter surface EXCLUDES migrations/ (degraded-DB preview needs no schema) and the hall', () => {
+  assert.ok(!access.STARTER_SPARSE_PATHS.includes('migrations'), 'migrations/ must stay out of the starter scope');
+  // the hall carved to modules/hall-ui/ in BV1.R85; it stays out of a starter box
+  assert.ok(!access.STARTER_SPARSE_PATHS.includes('modules/hall-ui'), 'modules/hall-ui (the hall) must stay out of the starter scope');
+  assert.ok(!access.STARTER_SPARSE_PATHS.includes('public-builders'), 'the old public-builders/ path must stay out of the starter scope');
+});
+
+console.log('\ndecideSourceAccess — the live per-fetch gate:');
+
+t('decideSourceAccess: active Xenos at the default floor → allowed, starter scope', () => {
+  const d = access.decideSourceAccess({ rank: 'xenos', status: 'active' });
+  assert.equal(d.allowed, true);
+  assert.equal(d.scope, 'starter');
+  assert.equal(d.spec.mode, 'sparse');
+});
+
+t('decideSourceAccess: active Metic → allowed, FULL scope (live rank, not stored scope)', () => {
+  const d = access.decideSourceAccess({ rank: 'metic', status: 'active' });
+  assert.equal(d.allowed, true);
+  assert.equal(d.scope, 'full');
+  assert.equal(d.spec.sparsePaths, null);
+});
+
+t('decideSourceAccess: Archon → full; Thetes → starter', () => {
+  assert.equal(access.decideSourceAccess({ rank: 'archon', status: 'active' }).scope, 'full');
+  assert.equal(access.decideSourceAccess({ rank: 'thetes', status: 'active' }).scope, 'starter');
+});
+
+t('decideSourceAccess: inactive builder → BUILDER_INACTIVE (checked BEFORE rank)', () => {
+  // A deactivated builder keeps a rank but loses access — and status is checked
+  // first, so even a Metic gets denied for inactivity, not a rank reason.
+  const d = access.decideSourceAccess({ rank: 'metic', status: 'inactive' });
+  assert.deepEqual(d, { allowed: false, reason: 'BUILDER_INACTIVE' });
+});
+
+t('decideSourceAccess: rank below an explicit floor → INSUFFICIENT_RANK with required+actual', () => {
+  const d = access.decideSourceAccess({ rank: 'xenos', status: 'active', floor: 'metic' });
+  assert.deepEqual(d, { allowed: false, reason: 'INSUFFICIENT_RANK', required: 'metic', actual: 'xenos' });
+});
+
+t('decideSourceAccess: unknown rank → INSUFFICIENT_RANK (fail closed), actual echoes the bad rank', () => {
+  const d = access.decideSourceAccess({ rank: 'wizard', status: 'active', floor: FLOOR });
+  assert.equal(d.allowed, false);
+  assert.equal(d.reason, 'INSUFFICIENT_RANK');
+  assert.equal(d.actual, 'wizard');
+});
+
+t('decideSourceAccess: missing rank → actual null (not undefined)', () => {
+  const d = access.decideSourceAccess({ status: 'active', floor: FLOOR });
+  assert.equal(d.allowed, false);
+  assert.equal(d.actual, null);
+});
+
+t('decideSourceAccess: status omitted (falsy) is treated as active — rank alone decides', () => {
+  const d = access.decideSourceAccess({ rank: 'metic' });
+  assert.equal(d.allowed, true);
+  assert.equal(d.scope, 'full');
+});
+
+console.log('\nreconcileSourceAccess — the slower droplet-level clawback/rescope:');
+
+t('reconcileSourceAccess: no box (none/destroyed/missing) → none/no-box', () => {
+  assert.deepEqual(access.reconcileSourceAccess({ boxState: 'none', rank: 'metic', status: 'active' }), { action: 'none', reason: 'no-box' });
+  assert.deepEqual(access.reconcileSourceAccess({ boxState: 'destroyed', rank: 'metic', status: 'active' }), { action: 'none', reason: 'no-box' });
+  assert.deepEqual(access.reconcileSourceAccess({ rank: 'metic', status: 'active' }), { action: 'none', reason: 'no-box' });
+});
+
+t('reconcileSourceAccess: inactive builder with a live box → deprovision (the clawback)', () => {
+  const d = access.reconcileSourceAccess({ boxScope: 'starter', boxState: 'active', rank: 'xenos', status: 'inactive' });
+  assert.deepEqual(d, { action: 'deprovision', reason: 'builder-inactive' });
+});
+
+t('reconcileSourceAccess: rank below floor → deprovision/below-floor', () => {
+  const d = access.reconcileSourceAccess({ boxScope: 'starter', boxState: 'active', rank: 'xenos', status: 'active', floor: 'metic' });
+  assert.deepEqual(d, { action: 'deprovision', reason: 'below-floor' });
+});
+
+t('reconcileSourceAccess: stored FULL box but live rank no longer Metic+ → deprovision (fresh box needed)', () => {
+  // A full box already holds the whole repo on disk; it cannot be safely
+  // downgraded in place, so the reconciler destroys it.
+  const d = access.reconcileSourceAccess({ boxScope: 'full', boxState: 'active', rank: 'thetes', status: 'active' });
+  assert.deepEqual(d, { action: 'deprovision', reason: 'scope-downgrade-needs-fresh-box' });
+});
+
+t('reconcileSourceAccess: stored STARTER box but live rank now Metic+ → rescope to full (graduation)', () => {
+  const d = access.reconcileSourceAccess({ boxScope: 'starter', boxState: 'active', rank: 'metic', status: 'active' });
+  assert.deepEqual(d, { action: 'rescope', reason: 'graduation', newScope: 'full' });
+});
+
+t('reconcileSourceAccess: scope already matches live rank → none/in-sync', () => {
+  assert.deepEqual(access.reconcileSourceAccess({ boxScope: 'starter', boxState: 'active', rank: 'xenos', status: 'active' }), { action: 'none', reason: 'in-sync' });
+  assert.deepEqual(access.reconcileSourceAccess({ boxScope: 'full', boxState: 'active', rank: 'metic', status: 'active' }), { action: 'none', reason: 'in-sync' });
+});
+
+t('reconcileSourceAccess: inactivity outranks an otherwise in-sync full Metic box', () => {
+  // status is checked before the scope comparison, so a deactivated Metic with a
+  // matching full box is still torn down.
+  const d = access.reconcileSourceAccess({ boxScope: 'full', boxState: 'active', rank: 'metic', status: 'inactive' });
+  assert.deepEqual(d, { action: 'deprovision', reason: 'builder-inactive' });
+});
+
+console.log(`\nbox_access.mjs: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/box_auth_check.mjs

@@ -0,0 +1,114 @@
+// tests/box_auth_check.mjs
+//
+// Unit tests for the dev-box session-start auth gate (task 1712). The pure core
+// `decideBoxAuth` is the high-risk surface: it decides whether a box session is
+// told to STOP and re-auth before it can safely claim/ship. The truth table
+// must be exactly right — box-scoped (source='box', ADR 0053) is the incident
+// case and must be caught from the local file alone (no network), an expired
+// real token must still be caught via the bounded /me probe, and any inability
+// to verify must FAIL OPEN (silent) rather than cry wolf.
+//
+// Importing the helper must NOT run its main() (which reads the session file and
+// hits the network) — box-auth-check.js guards main() behind
+// `require.main === module`, and only require()s cli-lib inside main(), so this
+// import is side-effect free (no I/O, no fetch). This test proves that holds.
+//
+// Run:  node tests/box_auth_check.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { decideBoxAuth } = require('../scripts/gds/box-auth-check.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+
+// A real, validated session on a box — the common clear-to-work case.
+const OK = { onBox: true, hasToken: true, isBoxScoped: false, meStatus: 200 };
+
+// ---------- skip: off a box, this check does nothing ----------
+
+test('not a box → skip (laptops are untouched, whatever the token looks like)', () => {
+  assert.equal(decideBoxAuth({ onBox: false, hasToken: false, isBoxScoped: false, meStatus: null }).action, 'skip');
+  assert.equal(decideBoxAuth({ onBox: false, hasToken: true, isBoxScoped: true, meStatus: 403 }).action, 'skip');
+});
+
+// ---------- setup: on a box with no session ----------
+
+test('box, no session → setup', () => {
+  const d = decideBoxAuth({ onBox: true, hasToken: false, isBoxScoped: false, meStatus: null });
+  assert.equal(d.action, 'setup');
+  assert.equal(d.reason, 'no-session');
+});
+
+// ---------- reauth: the box-scoped incident case (decided locally, no network) ----------
+
+test('box, box-scoped token → reauth (box-scoped), regardless of meStatus', () => {
+  const d = decideBoxAuth({ onBox: true, hasToken: true, isBoxScoped: true, meStatus: null });
+  assert.equal(d.action, 'reauth');
+  assert.equal(d.reason, 'box-scoped');
+});
+
+test('box-scoped is decided BEFORE meStatus — even a 200 stays reauth', () => {
+  // A box token can never legitimately 200 on /me, but the ordering guarantee is
+  // what keeps the incident case off the network path.
+  const d = decideBoxAuth({ onBox: true, hasToken: true, isBoxScoped: true, meStatus: 200 });
+  assert.equal(d.action, 'reauth');
+  assert.equal(d.reason, 'box-scoped');
+});
+
+// ---------- reauth: an expired/revoked real token (caught via the bounded /me) ----------
+
+test('box, real token, /me 401 → reauth (expired-or-revoked)', () => {
+  const d = decideBoxAuth({ ...OK, meStatus: 401 });
+  assert.equal(d.action, 'reauth');
+  assert.equal(d.reason, 'expired-or-revoked');
+});
+
+test('box, real token, /me 403 → reauth (expired-or-revoked)', () => {
+  const d = decideBoxAuth({ ...OK, meStatus: 403 });
+  assert.equal(d.action, 'reauth');
+  assert.equal(d.reason, 'expired-or-revoked');
+});
+
+// ---------- ok: a real, validated session ----------
+
+test('box, real token, /me 200 → ok (clear to work)', () => {
+  const d = decideBoxAuth(OK);
+  assert.equal(d.action, 'ok');
+  assert.equal(d.reason, 'validated');
+});
+
+// ---------- fail-open: couldn't verify → stay silent, never warn falsely ----------
+
+test('box, real token, /me not attempted (null) → skip (fail-open, no false alarm)', () => {
+  const d = decideBoxAuth({ ...OK, meStatus: null });
+  assert.equal(d.action, 'skip');
+  assert.equal(d.reason, 'unverified');
+});
+
+test('box, real token, /me 500 (server error) → skip (not a definitive auth failure)', () => {
+  const d = decideBoxAuth({ ...OK, meStatus: 500 });
+  assert.equal(d.action, 'skip');
+  assert.equal(d.reason, 'unverified');
+});
+
+test('box, real token, /me 502 (gateway) → skip (fail-open)', () => {
+  const d = decideBoxAuth({ ...OK, meStatus: 502 });
+  assert.equal(d.action, 'skip');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/box_code_staleness.mjs

@@ -0,0 +1,116 @@
+// tests/box_code_staleness.mjs
+//
+// Unit smoke for boxes.computeCodeStaleness (idea 332 / task 1316, ADR 0072) —
+// the pure "is this dev box running stale code?" decision behind the hall's
+// "rebuild to update" flag. No DB, no network.
+//
+// Run:  node tests/box_code_staleness.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const boxes = require('../modules/dev-box/boxes.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 NOW = Date.UTC(2026, 5, 20, 12, 0, 0); // fixed "now" so cases are deterministic
+const iso = (ms) => new Date(ms).toISOString();
+const HOUR = 3600 * 1000;
+const DAY = 24 * HOUR;
+
+console.log('computeCodeStaleness:');
+
+t('a parked/destroyed box is never judged (not_active)', () => {
+  for (const state of ['parked', 'destroyed', 'provisioning', 'none']) {
+    const r = boxes.computeCodeStaleness({ state, now: NOW });
+    assert.equal(r.stale, false, state);
+    assert.equal(r.reason, 'not_active', state);
+  }
+});
+
+t('active + never reported + just provisioned → not stale (awaiting first report)', () => {
+  const r = boxes.computeCodeStaleness({
+    state: 'active', provisionedAt: iso(NOW - 5 * 60 * 1000), codeReportedAt: null, now: NOW,
+  });
+  assert.equal(r.stale, false);
+  assert.equal(r.reason, 'awaiting_first_report');
+});
+
+t('active + never reported + past the provision grace → STALE (never_reported, ancient box)', () => {
+  const r = boxes.computeCodeStaleness({
+    state: 'active', provisionedAt: iso(NOW - 13 * DAY), codeReportedAt: null, now: NOW,
+  });
+  assert.equal(r.stale, true);
+  assert.equal(r.reason, 'never_reported');
+});
+
+t('active + reported a commit within the lag window → current', () => {
+  const r = boxes.computeCodeStaleness({
+    state: 'active',
+    provisionedAt: iso(NOW - 30 * DAY),
+    codeReportedAt: iso(NOW - 5 * 60 * 1000),
+    codeCommittedAt: iso(NOW - 3 * HOUR),     // box code is 3h behind deployed
+    serverCommittedAt: iso(NOW - 1 * HOUR),   // deployed commit is 1h old
+    now: NOW,
+  });
+  assert.equal(r.stale, false);
+  assert.equal(r.reason, 'current');
+});
+
+t('active + reported a commit > 2 days behind deployed → STALE (behind)', () => {
+  const r = boxes.computeCodeStaleness({
+    state: 'active',
+    provisionedAt: iso(NOW - 30 * DAY),
+    codeReportedAt: iso(NOW - 5 * 60 * 1000),
+    codeCommittedAt: iso(NOW - 9 * DAY),      // box stuck 9 days behind (pull not ff)
+    serverCommittedAt: iso(NOW - 1 * HOUR),
+    now: NOW,
+  });
+  assert.equal(r.stale, true);
+  assert.equal(r.reason, 'behind');
+  assert.ok(r.lag_ms > 2 * DAY);
+});
+
+t('reported but no commit dates to compare → not stale (unknown, never false-alarm)', () => {
+  const r = boxes.computeCodeStaleness({
+    state: 'active', provisionedAt: iso(NOW - 30 * DAY),
+    codeReportedAt: iso(NOW - 60 * 1000), codeCommittedAt: null, serverCommittedAt: null, now: NOW,
+  });
+  assert.equal(r.stale, false);
+  assert.equal(r.reason, 'unknown');
+});
+
+t('accepts Date objects as well as ISO strings', () => {
+  const r = boxes.computeCodeStaleness({
+    state: 'active',
+    provisionedAt: new Date(NOW - 30 * DAY),
+    codeReportedAt: new Date(NOW - 60 * 1000),
+    codeCommittedAt: new Date(NOW - 10 * DAY),
+    serverCommittedAt: new Date(NOW - HOUR),
+    now: NOW,
+  });
+  assert.equal(r.stale, true);
+  assert.equal(r.reason, 'behind');
+});
+
+t('exactly at the 2-day lag boundary is NOT stale (strictly greater)', () => {
+  const r = boxes.computeCodeStaleness({
+    state: 'active',
+    provisionedAt: iso(NOW - 30 * DAY),
+    codeReportedAt: iso(NOW - 60 * 1000),
+    codeCommittedAt: iso(NOW - (2 * DAY + HOUR)),
+    serverCommittedAt: iso(NOW - HOUR), // lag exactly 2 days
+    now: NOW,
+  });
+  assert.equal(r.stale, false);
+  assert.equal(r.reason, 'current');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);