@bongos/core 1.21.178 → 1.21.180

package/scripts/bongos/fitness-ratchets.js

@@ -240,6 +240,85 @@ function localKnipPath() {
 let knipSkipReason = null;
 function lastKnipSkipReason() { return knipSkipReason; }
 
+// ---- scoring knip's JSON (task 1004875) ----
+//
+// TWO THINGS THE OLD INLINE COUNT GOT WRONG, both found by putting modules/ in scope:
+//
+// 1. UNUSED FILES WERE NEVER COUNTED. It read a top-level `files` array; knip 6's
+//    JSON reporter has none — an unused file is an issue whose own `files` array is
+//    non-empty. So a brand-new dead file anywhere scored 0 and the ratchet waved it
+//    through. `files` is now one of the per-issue keys (the legacy top-level array is
+//    still read, for an older knip).
+//
+// 2. knip DOES NOT CREDIT A CommonJS NAMESPACE USE. Measured on a two-file repro:
+//    `const a = require('./a'); a.used()` leaves `used` reported as an unused export;
+//    only a destructured `const { used } = require('./a')` counts. src/ is mostly
+//    destructured (module-api.js says so), but modules/ is written the namespace way,
+//    so knip reports ~1,600 exports there that ARE used. Counting those would make
+//    every ordinary new export under modules/ red CI. So for a finding under
+//    modules/, an unused export counts only when its NAME appears in no other code
+//    file at all (a word match over .js/.mjs/.cjs/.html/.sh). That is the case knip
+//    is right about: exported, and nothing else even spells it. It under-counts (a
+//    name that happens to be spelled elsewhere hides) and never over-counts, which
+//    is the direction a gate that fails CI must err in. src/, scripts/ and tests/
+//    keep knip's own verdict, so their part of the baseline is unchanged.
+const KNIP_ISSUE_KEYS = ['files', 'dependencies', 'devDependencies', 'optionalPeerDependencies', 'unlisted', 'binaries', 'unresolved', 'exports', 'types', 'nsExports', 'nsTypes', 'duplicates'];
+const NAME_FILTERED_PREFIX = 'modules/';
+const WORD_SCAN_EXT_RE = /\.(m?js|cjs|html|sh)$/;
+const WORD_SCAN_SKIP = new Set(['node_modules', '.git', 'docs', 'public-docs', 'worktrees']);
+const WORD_RE = /[A-Za-z_$][\w$]*/g;
+
+// word -> the one repo-relative file that uses it, or true when 2+ files do.
+function codeWordIndex(root = ROOT) {
+  const index = new Map();
+  const walk = (dir) => {
+    let ents = [];
+    try { ents = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of ents) {
+      if (WORD_SCAN_SKIP.has(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      if (e.isDirectory()) { walk(abs); continue; }
+      if (!WORD_SCAN_EXT_RE.test(e.name)) continue;
+      let text;
+      try { text = fs.readFileSync(abs, 'utf8'); } catch { continue; }
+      const rel = path.relative(root, abs).split(path.sep).join('/');
+      for (const w of new Set(text.match(WORD_RE) || [])) {
+        const seen = index.get(w);
+        if (seen === undefined) index.set(w, rel);
+        else if (seen !== true && seen !== rel) index.set(w, true);
+      }
+    }
+  };
+  walk(root);
+  return index;
+}
+
+function nameUsedOutside(index, name, file) {
+  const seen = index.get(name);
+  return seen === true || (seen !== undefined && seen !== file);
+}
+
+// knip JSON -> the integer the ratchet scores. `wordIndex` is built on demand, and
+// only when a modules/ export finding needs it.
+function countKnipFindings(json, { root = ROOT, wordIndex = null } = {}) {
+  let total = Array.isArray(json && json.files) ? json.files.length : 0;
+  let index = wordIndex;
+  for (const issue of (json && json.issues) || []) {
+    const filtered = typeof issue.file === 'string' && issue.file.startsWith(NAME_FILTERED_PREFIX);
+    for (const key of KNIP_ISSUE_KEYS) {
+      const v = issue[key];
+      if (!Array.isArray(v)) continue;
+      if (filtered && (key === 'exports' || key === 'types')) {
+        if (!index) index = codeWordIndex(root);
+        total += v.filter((e) => !(e && nameUsedOutside(index, e.name, issue.file))).length;
+      } else {
+        total += v.length;
+      }
+    }
+  }
+  return total;
+}
+
 function knipIssueCount() {
   knipSkipReason = null;
   if (!localKnipPath()) {
@@ -259,22 +338,14 @@ function knipIssueCount() {
     if (e && e.stdout) { raw = e.stdout.toString(); }
     else { knipSkipReason = `npx knip failed to run in ${ROOT}`; return null; }
   }
+  let j;
   try {
-    const j = JSON.parse(raw);
-    // knip's json reporter: { files: [...], issues: [{ file, owners, exports:[], types:[], ... }] }
-    const files = Array.isArray(j.files) ? j.files.length : 0;
-    let items = 0;
-    for (const issue of j.issues || []) {
-      for (const key of ['dependencies', 'devDependencies', 'optionalPeerDependencies', 'unlisted', 'binaries', 'unresolved', 'exports', 'types', 'nsExports', 'nsTypes', 'duplicates']) {
-        const v = issue[key];
-        items += Array.isArray(v) ? v.length : 0;
-      }
-    }
-    return files + items;
+    j = JSON.parse(raw);
   } catch {
     knipSkipReason = 'knip produced output this script could not parse as JSON';
     return null;
   }
+  return countKnipFindings(j);
 }
 
 // ---------- baseline + ratchet ----------
@@ -586,6 +657,8 @@ module.exports = {
   consoleCallCount,
   isServerPath,
   knipIssueCount,
+  countKnipFindings,
+  codeWordIndex,
   localKnipPath,
   lastKnipSkipReason,
   OVERSIZE_LINES,

package/scripts/bongos/pulse.js

@@ -71,12 +71,14 @@ const REPO_ROOT = path.resolve(__dirname, '..', '..');
 // droplet machine without Postgres reachable).
 function loadDeps() {
   // eslint-disable-next-line global-require
-  const { pool } = require(path.join(REPO_ROOT, 'src/bongos/pool'));
+  const { pool } = require('../../src/bongos/pool');
   // eslint-disable-next-line global-require
   // pulse.js (the lib) carved → modules/sessions/ (BV1.R82 / ADR 0093 §1); the CLI
   // shell stays here and requires the module lib directly (scripts are outside the
-  // kernel boundary, so a direct module require is fine).
-  const { sweepStaleClaims } = require(path.join(REPO_ROOT, 'modules/sessions/pulse'));
+  // kernel boundary, so a direct module require is fine). A LITERAL path, not
+  // path.join: the dead-code scanner (knip) cannot follow a computed require, and
+  // reported the lib as an unused file while this was its only caller (task 1004875).
+  const { sweepStaleClaims } = require('../../modules/sessions/pulse');
   return { pool, sweepStaleClaims };
 }
 

package/scripts/bongos/repo-metrics.js

@@ -121,7 +121,9 @@ function scanDeadCode() {
     configured =
       !!pkg.knip ||
       fs.existsSync(path.join(REPO_ROOT, 'knip.json')) ||
-      fs.existsSync(path.join(REPO_ROOT, 'knip.jsonc'));
+      fs.existsSync(path.join(REPO_ROOT, 'knip.jsonc')) ||
+      // The config moved to a JS file so it can generate modules/ entries (task 1004875).
+      fs.existsSync(path.join(REPO_ROOT, 'knip.config.js'));
   } catch (_) {
     configured = false;
   }
@@ -163,7 +165,8 @@ function scanDeadCode() {
         return acc + ex + ty;
       }, 0);
       deadFiles = report.issues.reduce(
-        (acc, issue) => acc + (issue.files === true ? 1 : 0),
+        // knip 6 gives an ARRAY here ([{ name }]), not a bool (task 1004875).
+        (acc, issue) => acc + (issue.files === true || (Array.isArray(issue.files) && issue.files.length) ? 1 : 0),
         0
       );
     }

package/src/bongos/module-scope-map.js

@@ -427,6 +427,9 @@ const MODULE_GLOBS = {
     // scanner config above (task 1004146).
     '.gitignore', '.env.local.example',
     'package.json', 'package-lock.json',
+    // The dead-code scanner's config, moved out of package.json's "knip" key so it
+    // can generate modules/ entries from each module.json (task 1004875).
+    'knip.config.js',
     'scripts/bongos/fitness.js', 'scripts/bongos/docs-entropy.js',
     'scripts/bongos/redteam-patrol.js', 'scripts/bongos/audit-gate.js',
     'scripts/bongos/fitness-ratchets.js', 'scripts/bongos/control-manifest.js',

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.178'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.180'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/applicant_profile_boundary.mjs

@@ -737,8 +737,14 @@ test('this proof runs in a lane that actually executes', () => {
   const listed = runners.some((f) => {
     try { return fs.readFileSync(path.join(process.cwd(), 'tests', f), 'utf8').includes(self); } catch { return false; }
   });
-  const globbed = fs.existsSync(path.join(process.cwd(), 'package.json'))
-    && /tests\/\*|tests\/\*\*|\*\.mjs/.test(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8'));
+  // `npm test` is scripts/bongos/run-unit-tests.js, which readdir()s EVERY
+  // tests/*.mjs into the unit or the integration lane — no allowlist. (This used to
+  // regex package.json for a tests/** glob, which only ever matched the knip
+  // config's entry list; task 1004875 moved that out and the check went red.)
+  let testScript = '';
+  try { testScript = (JSON.parse(fs.readFileSync(path.join(process.cwd(), 'package.json'), 'utf8')).scripts || {}).test || ''; } catch { /* no package.json */ }
+  const globbed = /scripts\/bongos\/run-unit-tests\.js/.test(testScript)
+    && /readdirSync\(TESTS_DIR\)/.test(fs.readFileSync(path.join(process.cwd(), 'scripts/bongos/run-unit-tests.js'), 'utf8'));
   assert.ok(listed || globbed,
     `${self} is in no runner list and no glob — it would assert nothing forever (learning 1000218)`);
 });

package/tests/goal_sort_staleness.mjs

@@ -195,7 +195,7 @@ await test('the rollup activity clock is the SAME max(updated_at, shipped_at)',
 
 await test('Creator and Age are sent to the server, on BOTH board feeds', () => {
   assert.match(WORK_SRC, /function serverFilterQuery\(\)/);
-  assert.match(WORK_SRC, /tasks\/claimable\$\{serverFilterQuery\(\)\}/,
+  assert.match(WORK_SRC, /tasks\/claimable\?limit=\$\{CLAIMABLE_LIMIT\}\$\{serverFilterQuery\(\)/,
     'the claimable feed narrows at the source, not in the browser');
   assert.match(WORK_SRC, /tasks\?status=backlog&limit=\$\{BACKLOG_LIMIT\}\$\{q\}/,
     'and so does the backlog read');

package/tests/knip_modules_scope.mjs

@@ -0,0 +1,145 @@
+// tests/knip_modules_scope.mjs — the dead-code scanner covers modules/ (task 1004875).
+//
+// Three layers:
+//   1. the scorer (countKnipFindings) on synthetic knip JSON — hermetic;
+//   2. the generated entry list (knip.config.js) against the real modules/ tree —
+//      every route and poller a manifest declares is an entry, by the loader's rule;
+//   3. REAL knip on a throwaway fixture repo that uses the real config builder: a
+//      new unused file, and a new unused export, under modules/ each raise the score
+//      and the ratchet then fails. That layer needs knip in THIS checkout's
+//      node_modules (CI's `npm ci` provides it); without it, it skips and says why.
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const fr = require(path.join(ROOT, 'scripts/bongos/fitness-ratchets.js'));
+const knipConfig = require(path.join(ROOT, 'knip.config.js'));
+
+const issue = (file, extra) => ({ file, files: [], exports: [], types: [], dependencies: [], unlisted: [], ...extra });
+
+test('scorer: an unused FILE counts (knip 6 reports it per issue, not top-level)', () => {
+  const json = { issues: [issue('modules/x/orphan.js', { files: [{ name: 'modules/x/orphan.js' }] })] };
+  assert.equal(fr.countKnipFindings(json, { wordIndex: new Map() }), 1);
+});
+
+test('scorer: a modules/ export named by no other code file counts; one named elsewhere does not', () => {
+  const wordIndex = new Map([
+    ['usedViaNamespace', true], // two+ files spell it
+    ['onlyHere', 'modules/x/lib.js'], // only its own file
+    ['spelledInConsumer', 'modules/y/consumer.js'], // one OTHER file
+  ]);
+  const json = {
+    issues: [issue('modules/x/lib.js', {
+      exports: [{ name: 'usedViaNamespace' }, { name: 'onlyHere' }, { name: 'spelledInConsumer' }, { name: 'neverSpelled' }],
+    })],
+  };
+  assert.equal(fr.countKnipFindings(json, { wordIndex }), 2);
+});
+
+test('scorer: src/ exports keep knip\'s own verdict (no name filter outside modules/)', () => {
+  const wordIndex = new Map([['usedViaNamespace', true]]);
+  const json = { issues: [issue('src/x.js', { exports: [{ name: 'usedViaNamespace' }] })] };
+  assert.equal(fr.countKnipFindings(json, { wordIndex }), 1);
+});
+
+test('config: every manifest-declared route and poller is an entry, and the file exists', () => {
+  const entries = new Set(knipConfig.generatedModuleEntries(ROOT));
+  const modulesDir = path.join(ROOT, 'modules');
+  let checked = 0;
+  for (const key of fs.readdirSync(modulesDir)) {
+    const mf = path.join(modulesDir, key, 'module.json');
+    if (!fs.existsSync(mf)) continue;
+    const c = JSON.parse(fs.readFileSync(mf, 'utf8')).contributes || {};
+    for (const [dir, list] of [['routes', c.routes], ['pollers', c.pollers]]) {
+      for (const k of list || []) {
+        const rel = `modules/${key}/${dir}/${k}.js`;
+        assert.ok(entries.has(rel), `${rel} is declared in ${key}/module.json but is not a knip entry`);
+        assert.ok(fs.existsSync(path.join(ROOT, rel)), `${rel} is declared but missing`);
+        checked++;
+      }
+    }
+  }
+  assert.ok(checked > 50, `expected the real tree's routes+pollers, saw ${checked}`);
+  assert.ok(knipConfig.project.includes('modules/**/*.{js,mjs}'), 'modules/ must be in knip "project"');
+  assert.ok(entries.has('modules/ui-design/kit/render.js'), 'a #! CLI under modules/ is an entry');
+});
+
+// ---------- real knip on a fixture ----------
+
+const KNIP_BIN = path.join(ROOT, 'node_modules', 'knip', 'bin', 'knip.js');
+const HAVE_KNIP = fs.existsSync(KNIP_BIN);
+
+function write(root, rel, text) {
+  const abs = path.join(root, rel);
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, text);
+}
+
+function makeFixture() {
+  // realpath: on macOS os.tmpdir() is a /var -> /private/var symlink, and knip then
+  // resolves a require to a path outside its own project set and calls the target an
+  // unused file.
+  const dir = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'knip-modules-')));
+  write(dir, 'package.json', JSON.stringify({ name: 'knip-fixture', version: '1.0.0', private: true }));
+  // The fixture uses the REAL config builder, pointed at itself.
+  write(dir, 'knip.config.js',
+    `module.exports = require(${JSON.stringify(path.join(ROOT, 'knip.config.js'))}).buildConfig(__dirname);\n`);
+  write(dir, 'modules/demo/module.json', JSON.stringify({ key: 'demo', contributes: { routes: ['demo'] } }));
+  // The route requires the lib the namespace way — the shape knip is blind to.
+  write(dir, 'modules/demo/routes/demo.js',
+    "'use strict';\nconst lib = require('../lib');\nmodule.exports = function route() { return lib.hello(); };\n");
+  write(dir, 'modules/demo/lib.js',
+    "'use strict';\nfunction hello() { return 'hi'; }\nmodule.exports = { hello };\n");
+  return dir;
+}
+
+function score(dir) {
+  const raw = execFileSync(process.execPath, [KNIP_BIN, '--directory', dir, '--reporter', 'json', '--no-exit-code'], {
+    cwd: dir, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  return fr.countKnipFindings(JSON.parse(raw), { root: dir });
+}
+
+const ratchetFails = (value, baseline) =>
+  fr.compareToBaselines({ knip_issue_count: value }, { knip_issue_count: baseline }).violations.length > 0;
+
+test('real knip: a new unused file or export under modules/ fails the ratchet; a namespace-used export does not',
+  { skip: HAVE_KNIP ? false : `no knip at ${KNIP_BIN} — run \`npm ci\` (CI always has it)` }, () => {
+    const dir = makeFixture();
+    try {
+      const baseline = score(dir);
+      assert.equal(baseline, 0, 'the clean fixture scores 0 — the route is a generated entry, lib.hello is namespace-used');
+      assert.equal(ratchetFails(baseline, baseline), false);
+
+      // A new export that the route uses through the namespace: knip alone flags it;
+      // the scorer must not, or every ordinary export under modules/ would red CI.
+      write(dir, 'modules/demo/lib.js',
+        "'use strict';\nfunction hello() { return 'hi'; }\nfunction greet() { return 'yo'; }\nmodule.exports = { hello, greet };\n");
+      write(dir, 'modules/demo/routes/demo.js',
+        "'use strict';\nconst lib = require('../lib');\nmodule.exports = function route() { return lib.hello() + lib.greet(); };\n");
+      assert.equal(score(dir), baseline, 'a namespace-used export is not a finding');
+
+      // A new unused EXPORT.
+      write(dir, 'modules/demo/lib.js',
+        "'use strict';\nfunction hello() { return 'hi'; }\nfunction greet() { return 'yo'; }\n"
+        + "function zzDeadExport() { return 0; }\nmodule.exports = { hello, greet, zzDeadExport };\n");
+      const withExport = score(dir);
+      assert.equal(withExport, baseline + 1);
+      assert.equal(ratchetFails(withExport, baseline), true, 'an unused export under modules/ must fail the ratchet');
+
+      // A new unused FILE.
+      write(dir, 'modules/demo/orphan.js', "'use strict';\nmodule.exports = { nobodyCalls() { return 1; } };\n");
+      const withFile = score(dir);
+      assert.equal(withFile, withExport + 1);
+      assert.equal(ratchetFails(withFile, withExport), true, 'an unused file under modules/ must fail the ratchet');
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });

package/tests/work_board_live_refresh.mjs

@@ -0,0 +1,236 @@
+// tests/work_board_live_refresh.mjs — the Work board refreshes on the hall's live
+// signal, not a 20-second timer, and asks for a bounded claimable list (task 1004877).
+//
+// Before: an idle, visible Work tab re-fetched the WHOLE claimable feed every 20 s
+// (30 requests per 10 minutes) whether or not anything had changed. Now it listens
+// on the same live channel the hall home uses (GET /api/bongos/live, an
+// EventSource that says "something changed" and nothing else), re-fetches a
+// second after a change (at most one read per 20 s while changes keep coming), and
+// keeps a slow 2-minute timer as a backstop in case the live connection is down. Every claimable read carries ?limit= so the list it
+// returns has a ceiling.
+//
+// work.js is BOOTED in a vm here (the harness shape tests/hall_mine_lens.mjs uses)
+// against a fake clock and a fake EventSource, so the counts below are the real
+// page's timers, not a reading of its source.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+import { settle } from './helpers.mjs';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules', 'hall-ui', 'public');
+const read = (f) => fs.readFileSync(path.join(HALL, f), 'utf8');
+
+const MIN = 60 * 1000;
+
+// A virtual clock: setTimeout/setInterval queue here and only fire on advance(),
+// so ten minutes of page life run in milliseconds.
+function makeClock() {
+  let now = 1_000_000;
+  let seq = 0;
+  const timers = new Map();
+  const add = (fn, ms, every) => { seq += 1; timers.set(seq, { at: now + Math.max(0, Number(ms) || 0), fn, every }); return seq; };
+  return {
+    now: () => now,
+    setTimeout: (fn, ms) => add(fn, ms, 0),
+    setInterval: (fn, ms) => add(fn, ms, Math.max(1, Number(ms) || 1)),
+    clear: (id) => { timers.delete(id); },
+    async advance(ms) {
+      const end = now + ms;
+      for (;;) {
+        let next = null;
+        for (const [id, t] of timers) if (t.at <= end && (!next || t.at < next[1].at)) next = [id, t];
+        if (!next) break;
+        const [id, t] = next;
+        now = t.at;
+        if (t.every) t.at += t.every; else timers.delete(id);
+        t.fn();
+        await settle(); await settle();
+      }
+      now = end;
+      await settle();
+    },
+  };
+}
+
+function bootWorkBoard() {
+  const clock = makeClock();
+  const els = new Map();
+  const makeEl = (id = '') => ({
+    id, dataset: {}, style: {}, textContent: '', hidden: false, disabled: false,
+    checked: false, value: '', title: '', _html: '',
+    classList: { add() {}, remove() {}, toggle() { return false; }, contains() { return false; } },
+    setAttribute() {}, getAttribute() { return null; },
+    listeners: {},
+    addEventListener(type, fn) { (this.listeners[type] ||= []).push(fn); },
+    querySelector() { return null; }, querySelectorAll() { return []; },
+    appendChild() {}, remove() {}, closest() { return null; },
+    set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; },
+  });
+  const el = (key) => { if (!els.has(key)) els.set(key, makeEl(key)); return els.get(key); };
+  const documentObj = {
+    getElementById: (id) => el(id),
+    querySelector: (sel) => el(String(sel).replace(/^#/, '')),
+    querySelectorAll: () => [],
+    createElement: () => makeEl(),
+    addEventListener(type, fn) { (this.listeners[type] ||= []).push(fn); },
+    listeners: {},
+    body: { dataset: {} }, documentElement: { dataset: {} },
+    hidden: false,
+  };
+
+  const requests = [];
+  const client = {
+    request: async (method, url) => {
+      requests.push(url);
+      const ok = (data) => ({ status: 200, ok: true, data });
+      if (url.endsWith('/me')) return ok({ builder: { id: 7, github_login: 'percy', rank: 'metic' } });
+      if (url.endsWith('/goals')) return ok({ goals: [] });
+      if (url.includes('/tasks/claimable')) {
+        return ok({ claimable: [{ id: 501, title: 'a ready task', status: 'ready', version_id: 'V1' }], claimable_total: 1234, active_claims: [] });
+      }
+      return ok({});
+    },
+  };
+
+  // The fake live stream: one instance per `new EventSource(url)`.
+  const streams = [];
+  class FakeEventSource {
+    constructor(url) { this.url = url; this.readyState = 1; this.listeners = {}; streams.push(this); }
+    addEventListener(type, fn) { (this.listeners[type] ||= []).push(fn); }
+    emit(type) { (this.listeners[type] || []).forEach((fn) => fn({ data: '{}' })); }
+    close() { this.readyState = 2; }
+  }
+  FakeEventSource.CLOSED = 2;
+
+  const tabCounts = {};
+  const kit = {
+    makePager: (prefix) => ({ prefix, page: 1, perPage: 100 }),
+    paginate: (rows) => rows,
+    wirePager() {},
+    pagerBarHtml: () => '',
+    makeTabs: ({ tabs }) => ({ active: () => tabs[0].id, setCount(id, n) { tabCounts[id] = n; }, activate() {} }),
+    makeFilterBar: ({ search, primary = [], overflow = [] }) => {
+      [search, ...primary, ...overflow].filter(Boolean).forEach((c) => { el(c.id).value = c.value ?? c.default ?? ''; });
+      return { values: () => ({}), get: () => '', set() {} };
+    },
+    ageChipHtml: () => '',
+  };
+  const windowObj = {
+    __BRANDING__: { currency: { label: 'credits' } },
+    BongosClient: { createClient: () => client },
+    OTBKit: kit,
+    OTBTaskDetail: { href: (id) => `/task/${id}`, open() {} },
+    OTBTaskLib: {
+      priorityRank: () => 0, touchesConflict: () => false, conflictPeers: () => [], conflictChipHtml: () => '', rankTagHtml: () => '',
+      creditsPerMinute: () => 0, buildPromptForTask: () => '', friendlyBatchReason: () => '',
+      taskActivityMs: () => 0, STALE_CHOICES: [{ value: '', label: '— any —' }], isStale: () => false,
+      focusVersionDefault: () => null,
+    },
+    OTB: {
+      escapeHtml: (s) => String(s ?? ''), $: (sel) => documentObj.querySelector(sel),
+      fmtNum: (n) => String(n ?? 0), fmtDate: (d) => String(d ?? ''),
+      errCode: () => null, errDetails: () => ({}), toast() {}, categoryChip: () => '', fillKindFilter() {},
+      kindIsUnset: () => true, KIND_UNSET: 'unclassified', roleAxisLabel: () => 'Role',
+      roleOptions: () => [{ value: '', label: '— any —' }], roleIsUnset: () => true, roleLabel: () => '', ROLE_UNSET: 'unclassified',
+    },
+    location: { hostname: 'builders.example.com', pathname: '/work', search: '', hash: '', href: 'https://builders.example.com/work' },
+    localStorage: { getItem: () => null, setItem() {}, removeItem() {} },
+    confirm: () => true,
+    addEventListener() {},
+  };
+  class FakeDate extends Date {}
+  FakeDate.now = () => clock.now();
+  const sandbox = {
+    window: windowObj, document: documentObj, location: windowObj.location,
+    localStorage: windowObj.localStorage, console,
+    setTimeout: clock.setTimeout, clearTimeout: clock.clear, setInterval: clock.setInterval, clearInterval: clock.clear,
+    Date: FakeDate, URL, URLSearchParams, navigator: {}, history: { replaceState() {} },
+    EventSource: FakeEventSource,
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  for (const f of ['mine-lens.js', 'work-summary.js', 'claim-action.js', 'bulk-toolbar.js']) vm.runInContext(read(f), sandbox, { filename: f });
+  windowObj.OTBMineLens = sandbox.OTBMineLens;
+  windowObj.OTBWorkSummary = sandbox.OTBWorkSummary;
+  vm.runInContext(read('work.js'), sandbox, { filename: 'work.js' });
+  (documentObj.listeners.DOMContentLoaded || []).forEach((fn) => fn());
+
+  return {
+    clock, requests, streams, tabCounts,
+    claimableReads: () => requests.filter((u) => u.includes('/tasks/claimable')),
+    setHidden(h) { documentObj.hidden = h; (documentObj.listeners.visibilitychange || []).forEach((fn) => fn()); },
+  };
+}
+
+const boot = async () => {
+  const b = bootWorkBoard();
+  for (let i = 0; i < 8; i += 1) await settle();
+  await b.clock.advance(0);
+  return b;
+};
+
+test('every claimable read asks for a bounded list', async () => {
+  const b = await boot();
+  await b.clock.advance(10 * MIN);
+  const reads = b.claimableReads();
+  assert.ok(reads.length >= 1);
+  for (const u of reads) assert.match(u, /[?&]limit=\d+/, `unbounded claimable read: ${u}`);
+});
+
+test('the Ready tab count is the server total, not the length of the bounded list', async () => {
+  const b = await boot();
+  assert.equal(b.tabCounts.ready, 1234);
+});
+
+test('an idle visible tab makes at most 5 claimable reads in 10 minutes (was 30)', async () => {
+  const b = await boot();
+  const atLoad = b.claimableReads().length;
+  await b.clock.advance(10 * MIN);
+  const idle = b.claimableReads().length - atLoad;
+  assert.ok(idle <= 5, `expected ≤ 5 background reads per 10 min, got ${idle}`);
+  assert.ok(idle >= 4, `the slow fallback timer must still run (got ${idle})`);
+});
+
+test('the page subscribes to the live channel', async () => {
+  const b = await boot();
+  assert.equal(b.streams.length, 1);
+  assert.equal(b.streams[0].url, '/api/bongos/live');
+});
+
+test('a live nudge refreshes the claimable list within seconds', async () => {
+  const b = await boot();
+  const before = b.claimableReads().length;
+  b.streams[0].emit('nudge');
+  await b.clock.advance(3000);
+  assert.equal(b.claimableReads().length, before + 1);
+});
+
+test('a burst of nudges is coalesced: a busy minute costs at most 3 reads', async () => {
+  const b = await boot();
+  const before = b.claimableReads().length;
+  for (let s = 0; s < 60; s += 1) { b.streams[0].emit('nudge'); await b.clock.advance(1000); }
+  const n = b.claimableReads().length - before;
+  assert.ok(n >= 1 && n <= 3, `expected 1–3 reads for 60 nudges in a minute, got ${n}`);
+});
+
+test('a project changing every second never costs more than the old 20 s timer (30 per 10 min)', async () => {
+  const b = await boot();
+  const before = b.claimableReads().length;
+  for (let s = 0; s < 600; s += 1) { b.streams[0].emit('nudge'); await b.clock.advance(1000); }
+  const n = b.claimableReads().length - before;
+  assert.ok(n <= 30, `expected ≤ 30 reads in a busy 10 minutes, got ${n}`);
+});
+
+test('a hidden tab fetches nothing, on the timer or on a nudge', async () => {
+  const b = await boot();
+  b.setHidden(true);
+  const before = b.claimableReads().length;
+  b.streams[0].emit('nudge');
+  await b.clock.advance(10 * MIN);
+  assert.equal(b.claimableReads().length, before);
+});