@bongos/core 1.18.19 → 1.19.3

package/tests/governance_routes.mjs

@@ -0,0 +1,334 @@
+// tests/governance_routes.mjs — the governance CRUD API (BV1.R110, ADR 0151).
+//
+// Two layers, both DB-free (the memory_isolation.mjs pattern):
+//
+//   1. Gate classification + pins: route-rank-check's own classifier is run over
+//      the real routes source — every /governance route must gate on the
+//      `governance.manage` atom through real middleware, and every declared
+//      route must be pinned in MODULE_EXPECTED_RANKS. The pin set and the
+//      declared set are compared BOTH ways, so adding an unpinned governance
+//      route (or orphaning a pin) fails here before the grader sees it.
+//
+//   2. Real in-process HTTP through the actual router: express app + the real
+//      requirePermission gate resolving a STUB `governance` port on the seam,
+//      db sibling monkeypatched by property. What matters (ADR 0151 §2):
+//      system permissions are rejected as NON-GRANTABLE server-side, seeded
+//      rank-roles are immutable through this API (their grants derive from
+//      floors; their assignment derives from rank — R95b), and every route
+//      denies without the `governance.manage` grant.
+//
+// Run:  node tests/governance_routes.mjs
+
+import { strict as assert } from 'node:assert';
+import { test, after } from 'node:test';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+const seams = require(path.join(ROOT, 'src', 'module-seams.js'));
+const catalog = require(path.join(ROOT, 'modules', 'governance', 'catalog.js'));
+const govDb = require(path.join(ROOT, 'modules', 'governance', 'db.js'));
+const rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
+const { attachFail } = require(path.join(ROOT, 'src', 'bongos', 'middleware', 'error-envelope.js'));
+const express = require('express');
+
+const ROUTES_SRC = path.join(ROOT, 'modules', 'governance', 'routes', 'governance.js');
+
+// ===========================================================================
+// Layer 1 — gate classification + route-rank-check pins
+// ===========================================================================
+
+const classified = rrc.classifyText(fs.readFileSync(ROUTES_SRC, 'utf8'))
+  .filter((r) => r.route.startsWith('/governance'));
+
+test('the routes file declares the full R110 surface', () => {
+  const declared = new Set(classified.map((r) => r.key));
+  const wanted = [
+    'GET /governance/roles',
+    'GET /governance/permissions',
+    'GET /governance/assignments',
+    'POST /governance/roles',
+    'PUT /governance/roles/:roleKey/permissions/:permissionKey',
+    'DELETE /governance/roles/:roleKey/permissions/:permissionKey',
+    'POST /governance/assignments',
+    'DELETE /governance/assignments/:builderId/:roleKey',
+  ];
+  for (const key of wanted) assert.ok(declared.has(key), `missing route ${key}`);
+});
+
+test('every /governance route gates on governance.manage via REAL middleware', () => {
+  assert.ok(classified.length > 0, 'no /governance routes found to classify');
+  for (const r of classified) {
+    assert.equal(r.via, 'middleware', `${r.key}: gate must be middleware, not an annotation`);
+    assert.deepEqual(r.perms, ['governance.manage'], `${r.key}: must gate on exactly governance.manage`);
+    assert.equal(r.rank, 'archon', `${r.key}: governance.manage floors at archon`);
+  }
+});
+
+test('every declared /governance route is pinned, and every pin exists (both directions)', () => {
+  const pins = rrc.MODULE_EXPECTED_RANKS.governance;
+  assert.ok(pins, 'MODULE_EXPECTED_RANKS has no governance block');
+  const declared = new Set(classified.map((r) => r.key));
+  for (const key of declared) {
+    assert.equal(pins[key], `${rrc.PERM_PIN_PREFIX}governance.manage`,
+      `${key} must be pinned to perm:governance.manage`);
+  }
+  for (const key of Object.keys(pins)) {
+    assert.ok(declared.has(key), `pin ${key} names a route the file no longer declares`);
+  }
+});
+
+test('checkRouteRanks passes over the real tree (no governance findings)', () => {
+  const result = rrc.checkRouteRanks();
+  const ours = result.findings.filter((f) => String(f.file).includes('modules/governance/'));
+  assert.deepEqual(ours, [], `governance findings: ${JSON.stringify(ours, null, 2)}`);
+});
+
+// ===========================================================================
+// Layer 2 — real HTTP through the actual router (stub port + stubbed db)
+// ===========================================================================
+
+// The db stub: every function the routes call, recording args. Reset per test.
+const calls = [];
+const stub = {
+  listRolesWithGrants: async () => [{ role_key: 'metic', label: 'Metic', description: null, is_system: true, seeded_rank: 'metic', created_by: null, created_at: 't', permissions: ['task.create'] }],
+  listAssignments: async () => [{ builder_id: 7, github_login: 'x', display_name: 'X', rank: 'metic', role_key: 'metic', role_label: 'Metic', is_system: true, seeded_rank: 'metic', assigned_by: null, assigned_at: 't' }],
+  getRoleByKey: async (k) => (k === 'missing' ? null : { role_key: k, label: k, is_system: k === 'metic' || k === 'archon', seeded_rank: (k === 'metic' || k === 'archon') ? k : null }),
+  createRole: async (a) => ({ role_key: a.roleKey, label: a.label, description: a.description ?? null, is_system: false, seeded_rank: null, created_by: a.createdBy, created_at: 't' }),
+  grantRolePermission: async () => true,
+  revokeRolePermission: async () => true,
+  assignRole: async () => true,
+  unassignRole: async () => true,
+};
+const REAL = {};
+for (const k of Object.keys(stub)) {
+  REAL[k] = govDb[k];
+  govDb[k] = (...args) => { calls.push([k, ...args]); return stub[k](...args); };
+}
+
+// Fake the session (requireBuilder is captured at router build time), keep the
+// REAL requirePermission gate: it resolves the `governance` port per request, so
+// swapping the seam provider flips admit/deny without rebuilding the router.
+const realRequireBuilder = api.requireBuilder;
+api.requireBuilder = (req, res, next) => { req.builder = { id: 42, rank: 'archon' }; next(); };
+
+function grant(keys) {
+  seams._reset();
+  seams.registerProvider('governance', { resolveBuilderPermissions: async () => keys });
+}
+grant(['governance.manage']);
+
+const buildGovernanceRouter = require(path.join(ROOT, 'modules', 'governance', 'routes', 'governance.js'));
+const app = express();
+app.use(express.json());
+app.use(attachFail);
+app.use(buildGovernanceRouter());
+const server = http.createServer(app);
+await new Promise((r) => server.listen(0, '127.0.0.1', r));
+const BASE = `http://127.0.0.1:${server.address().port}`;
+
+after(() => {
+  server.close();
+  api.requireBuilder = realRequireBuilder;
+  for (const k of Object.keys(REAL)) govDb[k] = REAL[k];
+  seams._reset();
+});
+
+async function call(method, p, body) {
+  calls.length = 0;
+  const res = await fetch(`${BASE}${p}`, {
+    method,
+    headers: body === undefined ? {} : { 'content-type': 'application/json' },
+    body: body === undefined ? undefined : JSON.stringify(body),
+  });
+  let json = null;
+  try { json = await res.json(); } catch { /* no body */ }
+  return { status: res.status, json };
+}
+
+// --- the deny wall -----------------------------------------------------------
+
+test('without governance.manage EVERY route 403s (reads included)', async () => {
+  grant(['idea.triage', 'task.create']);
+  for (const [method, p] of [
+    ['GET', '/governance/roles'],
+    ['GET', '/governance/permissions'],
+    ['GET', '/governance/assignments'],
+    ['POST', '/governance/roles'],
+    ['PUT', '/governance/roles/r/permissions/task.create'],
+    ['DELETE', '/governance/roles/r/permissions/task.create'],
+    ['POST', '/governance/assignments'],
+    ['DELETE', '/governance/assignments/7/r'],
+  ]) {
+    const r = await call(method, p, method === 'GET' ? undefined : {});
+    assert.equal(r.status, 403, `${method} ${p} must deny`);
+    assert.equal(r.json.error.code, 'permission_forbidden', `${method} ${p}`);
+  }
+  grant(['governance.manage']);
+});
+
+// --- reads -------------------------------------------------------------------
+
+test('GET /governance/roles returns the role list with grants', async () => {
+  const r = await call('GET', '/governance/roles');
+  assert.equal(r.status, 200);
+  assert.equal(r.json.roles[0].role_key, 'metic');
+  assert.deepEqual(r.json.roles[0].permissions, ['task.create']);
+});
+
+test('GET /governance/permissions renders the catalog: grantable flags + principals, no DB call', async () => {
+  const r = await call('GET', '/governance/permissions');
+  assert.equal(r.status, 200);
+  assert.equal(calls.length, 0, 'the permission catalog is code, not a table');
+  const byKey = new Map(r.json.permissions.map((p) => [p.key, p]));
+  assert.equal(byKey.size, catalog.permissionKeys().length, 'every catalog key is listed');
+  const sys = byKey.get('governance.manage');
+  assert.equal(sys.system, true);
+  assert.equal(sys.grantable, false, 'a system permission renders non-grantable');
+  const op = byKey.get('idea.triage');
+  assert.equal(op.grantable, true);
+  assert.equal(op.floor, 'metic');
+  assert.ok(Array.isArray(r.json.principals), 'principals are listed read-only');
+  assert.ok(r.json.principals.every((p) => p.grantable === false));
+});
+
+test('GET /governance/assignments returns builder↔role rows', async () => {
+  const r = await call('GET', '/governance/assignments');
+  assert.equal(r.status, 200);
+  assert.equal(r.json.assignments[0].builder_id, 7);
+  assert.equal(r.json.assignments[0].role_key, 'metic');
+});
+
+// --- create role -------------------------------------------------------------
+
+test('POST /governance/roles creates a custom role, created_by = the session builder', async () => {
+  const r = await call('POST', '/governance/roles', { role_key: 'triage-helper', label: 'Triage helper' });
+  assert.equal(r.status, 201);
+  assert.equal(r.json.role.role_key, 'triage-helper');
+  assert.equal(r.json.role.is_system, false);
+  const c = calls.find(([k]) => k === 'createRole');
+  assert.equal(c[1].createdBy, 42, 'created_by must be the session builder, never input');
+});
+
+test('POST /governance/roles validates: label required, role_key must be a slug', async () => {
+  const missing = await call('POST', '/governance/roles', { role_key: 'x-role' });
+  assert.equal(missing.status, 400);
+  assert.equal(missing.json.error.code, 'validation_failed');
+  for (const bad of ['Has Space', 'UPPER', '-lead', 'dots.bad', '']) {
+    const r = await call('POST', '/governance/roles', { role_key: bad, label: 'L' });
+    assert.equal(r.status, 400, `role_key "${bad}" must be rejected`);
+  }
+  assert.equal(calls.filter(([k]) => k === 'createRole').length, 0, 'nothing reached the db');
+});
+
+test('POST /governance/roles maps a unique-violation to role_exists 409', async () => {
+  const prev = stub.createRole;
+  stub.createRole = async () => { const e = new Error('dup'); e.code = '23505'; throw e; };
+  const r = await call('POST', '/governance/roles', { role_key: 'metic-two', label: 'L' });
+  stub.createRole = prev;
+  assert.equal(r.status, 409);
+  assert.equal(r.json.error.code, 'role_exists');
+});
+
+// --- toggle a grant ----------------------------------------------------------
+
+test('PUT grant: an operational permission lands on a custom role', async () => {
+  const r = await call('PUT', '/governance/roles/triage-helper/permissions/idea.triage');
+  assert.equal(r.status, 200);
+  const c = calls.find(([k]) => k === 'grantRolePermission');
+  assert.deepEqual(c[1], { roleKey: 'triage-helper', permissionKey: 'idea.triage' });
+});
+
+test('PUT grant: a SYSTEM permission is rejected as non-grantable — the R110 wall', async () => {
+  for (const sysKey of ['governance.manage', 'deploy.push_main', 'builder.rank.set']) {
+    const r = await call('PUT', `/governance/roles/triage-helper/permissions/${sysKey}`);
+    assert.equal(r.status, 400, `${sysKey} must be refused`);
+    assert.equal(r.json.error.code, 'permission_not_grantable');
+    assert.equal(calls.filter(([k]) => k === 'grantRolePermission').length, 0, 'the refusal is BEFORE the db');
+  }
+});
+
+test('PUT grant: an unknown permission fails closed', async () => {
+  const r = await call('PUT', '/governance/roles/triage-helper/permissions/no.such.key');
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'unknown_permission');
+});
+
+test('PUT grant: a seeded rank-role is immutable (grants derive from floors)', async () => {
+  const r = await call('PUT', '/governance/roles/metic/permissions/idea.triage');
+  assert.equal(r.status, 403);
+  assert.equal(r.json.error.code, 'seeded_role_immutable');
+});
+
+test('PUT grant: an unknown role 404s', async () => {
+  const r = await call('PUT', '/governance/roles/missing/permissions/idea.triage');
+  assert.equal(r.status, 404);
+  assert.equal(r.json.error.code, 'role_not_found');
+});
+
+test('DELETE grant revokes without consulting the catalog (stale keys stay removable)', async () => {
+  const r = await call('DELETE', '/governance/roles/triage-helper/permissions/some.retired.key');
+  assert.equal(r.status, 200);
+  const c = calls.find(([k]) => k === 'revokeRolePermission');
+  assert.deepEqual(c[1], { roleKey: 'triage-helper', permissionKey: 'some.retired.key' });
+});
+
+test('DELETE grant on a seeded rank-role is refused like the PUT', async () => {
+  const r = await call('DELETE', '/governance/roles/archon/permissions/idea.triage');
+  assert.equal(r.status, 403);
+  assert.equal(r.json.error.code, 'seeded_role_immutable');
+});
+
+// --- assignments -------------------------------------------------------------
+
+test('POST /governance/assignments assigns a custom role, assigned_by = the session builder', async () => {
+  const r = await call('POST', '/governance/assignments', { builder_id: 7, role_key: 'triage-helper' });
+  assert.equal(r.status, 201);
+  const c = calls.find(([k]) => k === 'assignRole');
+  assert.deepEqual(c[1], { builderId: 7, roleKey: 'triage-helper', assignedBy: 42 });
+});
+
+test('POST /governance/assignments refuses a seeded rank-role (rank is the writer — R95b)', async () => {
+  const r = await call('POST', '/governance/assignments', { builder_id: 7, role_key: 'archon' });
+  assert.equal(r.status, 403);
+  assert.equal(r.json.error.code, 'seeded_role_assignment_forbidden');
+  assert.equal(calls.filter(([k]) => k === 'assignRole').length, 0);
+});
+
+test('POST /governance/assignments maps a missing builder (FK) to 404', async () => {
+  const prev = stub.assignRole;
+  stub.assignRole = async () => { const e = new Error('fk'); e.code = '23503'; throw e; };
+  const r = await call('POST', '/governance/assignments', { builder_id: 999, role_key: 'triage-helper' });
+  stub.assignRole = prev;
+  assert.equal(r.status, 404);
+  assert.equal(r.json.error.code, 'builder_not_found');
+});
+
+test('POST /governance/assignments validates builder_id and role_key', async () => {
+  const r = await call('POST', '/governance/assignments', { builder_id: 'seven', role_key: 'triage-helper' });
+  assert.equal(r.status, 400);
+  assert.equal(r.json.error.code, 'validation_failed');
+});
+
+test('DELETE /governance/assignments/:builderId/:roleKey unassigns a custom role', async () => {
+  const r = await call('DELETE', '/governance/assignments/7/triage-helper');
+  assert.equal(r.status, 200);
+  const c = calls.find(([k]) => k === 'unassignRole');
+  assert.deepEqual(c[1], { builderId: 7, roleKey: 'triage-helper' });
+});
+
+test('DELETE /governance/assignments refuses a seeded rank-role', async () => {
+  const r = await call('DELETE', '/governance/assignments/7/metic');
+  assert.equal(r.status, 403);
+  assert.equal(r.json.error.code, 'seeded_role_assignment_forbidden');
+});
+
+test('DELETE /governance/assignments validates the builder id param', async () => {
+  const r = await call('DELETE', '/governance/assignments/not-a-number/triage-helper');
+  assert.equal(r.status, 400);
+});

package/tests/grader.mjs

@@ -1410,12 +1410,16 @@ await testAsync('v4 runWorker (#465): one retry only — if the retry also error
 
 // --- #467: per-worker timeouts + transient-error set + audit-exports core ---
 
-test('v4 #467: timeoutForWorker gives Read-heavy workers a longer budget', () => {
+test('v4 #467 / task 1002580: every gating/advisory worker gets the 360s heavy-tier budget', () => {
+  // task 1002580: Hacker/Efficiency were 240s on the (false) assumption they are
+  // "light". On a security- or perf-heavy diff those lenses ARE the heavy ones,
+  // and a gating-worker timeout hard-blocks — so all four now share 360s. Worst-
+  // case wall time is unchanged (parallel workers; max was already 360s).
   const tfw = grader.WORKERS.timeoutForWorker;
   assert.equal(tfw({ KIND: 'narc' }, {}), 360000);
   assert.equal(tfw({ KIND: 'quality' }, {}), 360000);
-  assert.equal(tfw({ KIND: 'hacker' }, {}), 240000);
-  assert.equal(tfw({ KIND: 'efficiency' }, {}), 240000);
+  assert.equal(tfw({ KIND: 'hacker' }, {}), 360000);
+  assert.equal(tfw({ KIND: 'efficiency' }, {}), 360000);
 });
 
 test('v4 #467: an explicit module MAX_TIMEOUT_MS overrides the KIND map', () => {

package/tests/hall_nav.mjs

@@ -127,14 +127,20 @@ function hrefResolves(item) {
 
 test('sidebar groups read by audience, in order', () => {
   const nav = parseNav(boot().sidebarHtml);
-  assert.deepEqual(nav.map((g) => g.label), ['', 'You', 'Community', 'Docs', 'Archon']);
+  // 'Archon' → 'Governance' in ADR 0157: the group's pages opened to Metic, so a header
+  // reading "Archon" over items a Metic can open would misdescribe the ladder.
+  assert.deepEqual(nav.map((g) => g.label), ['', 'You', 'Community', 'Docs', 'Governance']);
   assert.deepEqual(nav[0].items.map((i) => i.id), ['home', 'roadmap', 'goals', 'work'],
     'the unlabeled group is the project itself (task 1002425 order)');
   assert.deepEqual(nav[1].items.map((i) => i.id), ['standing', 'profile'], 'You = your own numbers');
-  assert.deepEqual(nav[2].items.map((i) => i.id), ['leaderboard'], 'Community = everyone else');
+  // People (task 1002577): the /scouting directory graduated into the hall.
+  // Archon-gated cosmetically to match its data endpoint; requireProjectCuratePage
+  // is the wall server-side.
+  assert.deepEqual(nav[2].items.map((i) => i.id), ['leaderboard', 'people'], 'Community = everyone else');
   assert.deepEqual(nav[3].items.map((i) => i.id),
     ['primer', 'ranks', 'economy', 'diagrams', 'atlas', 'modules', 'apidocs'], 'Docs = reference material');
-  assert.deepEqual(nav[4].items.map((i) => i.id), ['watch', 'harbor', 'gate', 'sessions']);
+  // 'governance' (the Roles tab, BV1.R113) is the group's one archon-gated item.
+  assert.deepEqual(nav[4].items.map((i) => i.id), ['watch', 'harbor', 'gate', 'sessions', 'governance']);
 });
 
 test('Economy lives in Docs and points at the reward-schedule page', () => {
@@ -183,7 +189,11 @@ test('Achievements has no nav entry, but #achievements still routes to Standing'
 
 test('collapsible groups carry a stable storage key (collapse persistence)', () => {
   const html = boot().sidebarHtml;
-  for (const g of ['you', 'community', 'docs', 'archon']) {
+  // 'archon' → 'governance' follows the ADR 0157 relabel. The slug is the
+  // hall-nav-collapsed storage key, so any builder who had collapsed the old "archon"
+  // group gets the new one expanded once — cosmetic, and preferable to keeping a stale
+  // slug that no longer matches the visible label.
+  for (const g of ['you', 'community', 'docs', 'governance']) {
     assert.match(html, new RegExp(`data-group="${g}"`), `${g} is collapsible (hall-nav-collapsed key)`);
   }
   assert.ok(!/nav-group--collapsible[^>]*>(?!<button)/.test(html.split('<div class="nav-group')[1] || ''),

package/tests/helpers.mjs

@@ -50,3 +50,76 @@ export function makeSqlAwareClient(handler) {
   };
   return { connect: async () => client, _client: client, queries };
 }
+
+// ---------------------------------------------------------------------------
+// Host-topology guards (task 1002470). Pattern established by task 1002234 in
+// tests/stop_refcheck.mjs, generalised here.
+//
+// tests/ is PUBLISHABLE, but the paths some tests assert are on
+// publish-manifest.js's PROTECTED_TOPOLOGY_EXCLUDE list (`.claude/hooks/`,
+// `.claude/settings.json`, `infra/`, `.github/`, `scripts/deploy/`) or are
+// instance-only content (`devbox-app/`, `config/<instance>.json`). A neutral
+// core checkout carries none of it, so an unconditional load CRASHED the file
+// at import and red-X'd the unit gate for every consumer.
+//
+// These skip cleanly when the topology is absent and run in FULL when it is
+// present — no assertion is weakened, only deferred to the layout that has the
+// thing under test. tests/host_topology_skips.mjs ratchets the roster so a new
+// skip cannot be added silently.
+// ---------------------------------------------------------------------------
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+export const SKIP_MARKER = 'HOST-TOPOLOGY-SKIP';
+
+function emitSkip(missing, note) {
+  console.log(`${SKIP_MARKER}: absent from this checkout — ${missing.join(', ')}`);
+  console.log(`  ${note || 'Host/instance topology the neutral core does not carry (publish-manifest.js PROTECTED_TOPOLOGY_EXCLUDE).'}`);
+  console.log('  This file runs in full on an instance where the topology is materialized.');
+  process.exit(0);
+}
+
+// Exit 0 with a SKIP line unless every repo-relative path exists.
+export function skipUnlessPresent(relPaths, note) {
+  const wanted = Array.isArray(relPaths) ? relPaths : [relPaths];
+  const missing = wanted.filter((p) => !fs.existsSync(path.join(ROOT, p)));
+  if (missing.length) emitSkip(missing, note);
+}
+
+// onDiskModuleKeys — the module roster read STRAIGHT FROM DISK (task 1002470).
+//
+// Several tests compare a component's idea of the installed modules against this.
+// The independence is the whole point, and it is a real check rather than a
+// tautology *because this reads disk directly* — not through fitness.js's
+// discoveredModuleKeys(), gen-atlas's listDir(), or the module loader. If any of
+// those drops, adds, or mis-kinds a module, its answer diverges from this one and
+// the comparing test fails. (Task 1002449 flagged exactly this trap: a check that
+// asks the component under test what it found can never catch the component being
+// wrong.) Living here rather than being copy-pasted per test keeps that rationale
+// stated once — the callers just compare.
+//
+// Deliberately NOT the same shape as the production discovery: a directory counts
+// only if it carries a module.json, which is what makes a module a module.
+export function onDiskModuleKeys(modulesDir = path.join(ROOT, 'modules')) {
+  return fs.readdirSync(modulesDir, { withFileTypes: true })
+    .filter((e) => e.isDirectory() && fs.existsSync(path.join(modulesDir, e.name, 'module.json')))
+    .map((e) => e.name)
+    .sort();
+}
+
+// require() a host-topology module, skipping the file if THAT module is absent.
+// A MODULE_NOT_FOUND naming anything else is a genuine broken dependency and
+// still throws — masking it would hide a real regression.
+export function requireHostModule(require, spec, note) {
+  try {
+    return require(spec);
+  } catch (err) {
+    if (err && err.code === 'MODULE_NOT_FOUND' && String(err.message).includes(`'${spec}'`)) {
+      emitSkip([spec], note);
+    }
+    throw err;
+  }
+}

package/tests/hook_core_resolve.mjs

@@ -28,10 +28,11 @@ import { tmpdir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { requireHostModule } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
-const resolver = require('../.claude/hooks/_core-resolve.js');
+const resolver = requireHostModule(require, '../.claude/hooks/_core-resolve.js');
 
 let passed = 0;
 let failed = 0;

package/tests/host_topology_skips.mjs

@@ -0,0 +1,97 @@
+// tests/host_topology_skips.mjs — the RATCHET on host-topology skips (task 1002470).
+//
+// tests/ is publishable, but some tests assert paths the neutral core deliberately does
+// not carry: publish-manifest.js's PROTECTED_TOPOLOGY_EXCLUDE (`.claude/hooks/`,
+// `.claude/settings.json`, `infra/`, `.github/`, `scripts/deploy/`) plus instance-only
+// content (`devbox-app/`, `config/<instance>.json`, an uninstalled module). Those files
+// used to CRASH at import and red-X the unit gate for every consumer; they now skip
+// cleanly via the helpers in tests/helpers.mjs and run in full wherever the topology is
+// materialized.
+//
+// A skip is real coverage that does not execute here, so it must never be the quiet
+// default. This file is the explicit, justified allowlist the fix is ratcheted against:
+//   - a NEW file taking a whole-file skip fails until it is added here deliberately;
+//   - a file that stops needing one fails until it is removed, so the roster can't rot.
+//
+// This deliberately does NOT cover per-assertion guards (a single `if (!existsSync) return`
+// inside one test of an otherwise-running file) — those leave the file's other assertions
+// executing. Only whole-file skips, which turn an entire file into a no-op, are ratcheted.
+//
+// DB-free, no network. Run: node tests/host_topology_skips.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const TESTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+
+// Every test file permitted to skip itself wholesale, with the topology it needs.
+// Adding a line here is a deliberate, reviewable act — that is the point.
+const ALLOWED = {
+  art_stage: 'scripts/gds/art-stage.js (art-pipeline tooling, not in the core)',
+  bongos_downloads: 'config/bongos-cli.json (instance content)',
+  box_dns_repoint: 'infra/box-dns-cloudflare.sh (host topology)',
+  box_ship_permissions: '.claude/settings.json (package-excluded)',
+  conductor: '.claude/hooks/conductor.js (package-excluded)',
+  deploy_instance: 'scripts/deploy/deploy-instance.sh (host topology)',
+  devbox_downloads: 'config/devbox-app.json (instance content)',
+  eviction_policy: '.claude/hooks/eviction-policy.js (package-excluded)',
+  first_run_engine_check: '.claude/hooks/session-start.js (package-excluded)',
+  hook_core_resolve: '.claude/hooks/_core-resolve.js (package-excluded)',
+  'lifecycle-card': '.claude/hooks/lifecycle-card.js (package-excluded)',
+  pre_compact: '.claude/hooks/pre-compact.js (package-excluded)',
+  preview_server: 'src/preview-server.js (game module, not in the core)',
+  recall_hints: '.claude/hooks/recall-hints.js (package-excluded)',
+  rubric_fixtures: 'modules/art-pipeline/template/rubric_fixtures (module not installed)',
+  run_routine_two_root: '.claude/hooks/_core-resolve.js (package-excluded)',
+  'session-cards': '.claude/hooks/session-cards.js (package-excluded)',
+  session_start_freshness: '.claude/hooks/session-start.js (package-excluded)',
+  stop_refcheck: '.claude/hooks/stop-refcheck.js (package-excluded; the task-1002234 precedent)',
+  worktree_guard: '.claude/hooks/worktree-guard.js (package-excluded)',
+};
+
+// A file takes a whole-file skip if it calls either helper, or hand-rolls the same
+// exit-0-on-MODULE_NOT_FOUND shape that task 1002234 established in stop_refcheck.
+const HELPER_CALL = /\b(skipUnlessPresent|requireHostModule)\s*\(/;
+const HANDROLLED = /MODULE_NOT_FOUND[\s\S]{0,400}?process\.exit\(0\)/;
+
+function filesTakingWholeFileSkip() {
+  return fs.readdirSync(TESTS_DIR)
+    .filter((f) => f.endsWith('.mjs') && f !== 'helpers.mjs' && f !== path.basename(fileURLToPath(import.meta.url)))
+    .filter((f) => {
+      const src = fs.readFileSync(path.join(TESTS_DIR, f), 'utf8');
+      return HELPER_CALL.test(src) || HANDROLLED.test(src);
+    })
+    .map((f) => f.replace(/\.mjs$/, ''))
+    .sort();
+}
+
+test('every host-topology skip is on the allowlist — the set cannot grow silently', () => {
+  const actual = filesTakingWholeFileSkip();
+  const allowed = Object.keys(ALLOWED).sort();
+  const added = actual.filter((f) => !allowed.includes(f));
+  assert.deepEqual(added, [],
+    'these test files skip themselves but are not on the allowlist. A skip means the file '
+    + 'asserts nothing here — add it to ALLOWED in tests/host_topology_skips.mjs with the '
+    + 'topology it needs, or make the test run without that topology.');
+});
+
+test('the allowlist has no stale entries — a file that no longer skips must be removed', () => {
+  const actual = filesTakingWholeFileSkip();
+  const stale = Object.keys(ALLOWED).sort().filter((f) => !actual.includes(f));
+  assert.deepEqual(stale, [],
+    'these files are on the allowlist but no longer take a host-topology skip — drop them '
+    + 'from ALLOWED so the roster keeps meaning something.');
+});
+
+test('the ratchet is non-vacuous and actually detects a skip', () => {
+  // If the detection regexes ever stopped matching, both checks above would pass while
+  // proving nothing. Pin that they see the real thing.
+  const actual = filesTakingWholeFileSkip();
+  assert.ok(actual.length >= 15, `expected the known skip set, found ${actual.length}`);
+  assert.ok(actual.includes('stop_refcheck'), 'the hand-rolled precedent must still be detected');
+  assert.ok(actual.includes('conductor'), 'a requireHostModule caller must be detected');
+  assert.ok(actual.includes('box_dns_repoint'), 'a skipUnlessPresent caller must be detected');
+});

package/tests/infra_exec_paths.mjs

@@ -31,8 +31,18 @@ function test(name, fn) {
   catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
 }
 
+// infra/ is HOST topology (publish-manifest.js PROTECTED_TOPOLOGY_EXCLUDE) — the neutral
+// core carries no units and no launcher (task 1002470). The checks that read the REAL tree
+// only mean something where that tree exists; the synthetic counterfactuals below always run.
+const HAS_INFRA = fs.existsSync(path.join(REPO, 'infra'));
+const HAS_LAUNCHER = fs.existsSync(LAUNCHER);
+function hostTest(name, present, fn) {
+  if (!present) { console.log(`  skip ${name} — infra/ is absent in this checkout (host topology)`); return; }
+  test(name, fn);
+}
+
 // ---- A. the lint is green on the real tree, and covers all 11 core-script units ----------------
-test('lint-infra-exec: every core-script unit resolves in a consumer layout (publishable + present)', () => {
+hostTest('lint-infra-exec: every core-script unit resolves in a consumer layout (publishable + present)', HAS_INFRA, () => {
   const r = lintInfraExec({ instanceRoot: REPO, coreRoot: REPO });
   assert.deepEqual(r.violations, [], `expected no violations, got: ${JSON.stringify(r.violations)}`);
   assert.ok(r.ok, 'lint should pass');
@@ -68,7 +78,7 @@ function runLauncher(rel, instanceRoot) {
   }).trim();
 }
 
-test('core-node.sh resolves the monolith layout (script at the instance root)', () => {
+hostTest('core-node.sh resolves the monolith layout (script at the instance root)', HAS_LAUNCHER, () => {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cn-mono-'));
   try {
     fs.mkdirSync(path.join(tmp, 'scripts', 'gds'), { recursive: true });
@@ -77,7 +87,7 @@ test('core-node.sh resolves the monolith layout (script at the instance root)',
   } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
 });
 
-test('core-node.sh falls back to the consumer layout (script only under node_modules/@bongos/core)', () => {
+hostTest('core-node.sh falls back to the consumer layout (script only under node_modules/@bongos/core)', HAS_LAUNCHER, () => {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cn-cons-'));
   try {
     const pkgDir = path.join(tmp, 'node_modules', '@bongos', 'core', 'scripts', 'gds');
@@ -88,7 +98,7 @@ test('core-node.sh falls back to the consumer layout (script only under node_mod
   } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
 });
 
-test('core-node.sh exits non-zero when the script is in NO layout', () => {
+hostTest('core-node.sh exits non-zero when the script is in NO layout', HAS_LAUNCHER, () => {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cn-none-'));
   let threw = false;
   try {