@bongos/core 1.21.181 → 1.22.1

package/scripts/bongos/escape-helper-guard.js

@@ -0,0 +1,147 @@
+// scripts/bongos/escape-helper-guard.js — fitness check: ONE HTML escaper per side
+// (task 1004876, goal 1000135).
+//
+// WHY. The HTML escaper is what keeps a builder's own text (a task title, an idea,
+// a goal name) from turning into live markup on someone else's screen. The
+// 2026-10-25 audit found ~45 private copies of it, and six of them escaped fewer
+// characters than the rest (no single quote) or printed "null" for a missing
+// value — each one a place a cross-site-scripting hole could hide. They were
+// collapsed onto exactly two definitions:
+//
+//   browser  modules/hall-ui/public/dom-utils.js  → window.OTB.escapeHtml
+//   server   src/html-escape.js                    → escapeHtml (modules reach it
+//                                                   through src/module-api.js)
+//
+// This check keeps it that way. It does not look for a NAME (a copy called
+// `hesc` or `sesc` hid from a name search) — it looks for the escape TABLE
+// itself: a quoted < string literal is what every hand-rolled escaper has
+// to contain, and nothing else in the code needs one. A file that contains one
+// outside the allow-list below is a new private escaper: delete it and call the
+// shared one (a thin `function esc(s) { return window.OTB.escapeHtml(s); }`
+// delegate is fine — it holds no table).
+//
+// A delegate must really delegate, though. primer.js used to fall back to
+// `(s) => String(s)` — an "escaper" with no table that escaped nothing — so a
+// local HTML-escaper NAME (esc / escapeHtml / escAttr / escHtml / hesc / sesc)
+// must point at a shared escaper on the line that defines it. In browser code
+// (modules/*/public/) every such name is checked; on the server `esc` alone is
+// exempt, because scripts there use it for regex and markdown escaping too.
+//
+// Second half: a hall page must load dom-utils.js as its FIRST hall script and
+// without `defer`/`async`, because shell.js, palette.js and craft-mode.js run
+// while the page parses and now escape through window.OTB.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { REPO_ROOT } = require('./fitness-lib.js');
+
+// The two shared escapers, plus the one file whose escaper is NOT an HTML one.
+const ALLOWED = new Map([
+  ['modules/hall-ui/public/dom-utils.js', 'the shared BROWSER escaper (window.OTB.escapeHtml)'],
+  ['src/html-escape.js', 'the shared SERVER escaper (module-api escapeHtml)'],
+  ['modules/copy-desk/docx.js', 'an XML escaper for .docx files (', drops control characters) — a different contract'],
+]);
+
+// Where code lives. Tests, docs and vendored bundles are out of scope: a test may
+// carry its own decoder/encoder to CHECK the shared one against.
+const SCAN_ROOTS = ['src', 'scripts', 'modules', 'server.js', 'bin'];
+const SCAN_EXT = /\.(c|m)?js$|\.html$/;
+const SKIP_DIR = new Set(['node_modules', '.git', 'tests', 'fixtures']);
+
+// A quoted < literal — the entity standing alone as a string in any quote style.
+const ESCAPE_TABLE_RE = /(['"`])<\1/;
+
+function walk(abs, out) {
+  let st;
+  try { st = fs.statSync(abs); } catch { return out; }
+  if (st.isFile()) { if (SCAN_EXT.test(abs)) out.push(abs); return out; }
+  for (const ent of fs.readdirSync(abs, { withFileTypes: true })) {
+    if (SKIP_DIR.has(ent.name)) continue;
+    walk(path.join(abs, ent.name), out);
+  }
+  return out;
+}
+
+// findEscapeTables(text) → 1-based line numbers holding a hand-rolled escape table.
+function findEscapeTables(text) {
+  const lines = String(text).split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) if (ESCAPE_TABLE_RE.test(lines[i])) hits.push(i + 1);
+  return hits;
+}
+
+// findFakeDelegates(text, { browser }) → 1-based lines that define a local HTML
+// escaper name WITHOUT pointing it at a shared escaper (window.OTB.escapeHtml, a
+// kit/reader alias of it, api.escapeHtml, or src/html-escape.js).
+const BROWSER_NAMES = /(?:function\s+|(?:const|let|var)\s+)(esc|escapeHtml|escAttr|escHtml|hesc|sesc)\s*(?:\(|=)/;
+const SERVER_NAMES = /(?:function\s+|(?:const|let|var)\s+)(escapeHtml|escAttr|escHtml|hesc|sesc)\s*(?:\(|=)/;
+const POINTS_AT_SHARED = /\.escapeHtml\b|\.esc\b|\bescapeHtml;|require\([^)]*html-escape/;
+function findFakeDelegates(text, { browser = false } = {}) {
+  const lines = String(text).split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(browser ? BROWSER_NAMES : SERVER_NAMES);
+    if (!m) continue;
+    if (!POINTS_AT_SHARED.test(lines[i].slice(m.index + m[0].length))) hits.push(i + 1);
+  }
+  return hits;
+}
+
+// hallPageOrderProblem(html) → null when the page is fine, else a sentence saying
+// why. A page loading no /builders/ script at all has nothing to order.
+function hallPageOrderProblem(html) {
+  const tags = [...String(html).matchAll(/<script\b[^>]*\bsrc=["']([^"']+)["'][^>]*>/g)]
+    .map((m) => ({ tag: m[0], src: m[1].split('?')[0] }))
+    .filter((t) => t.src.startsWith('/builders/'));
+  if (!tags.length) return null;
+  const at = tags.findIndex((t) => t.src === '/builders/dom-utils.js');
+  if (at < 0) return 'loads hall scripts but never /builders/dom-utils.js (window.OTB.escapeHtml would be undefined)';
+  if (at > 0) return `loads ${tags[0].src} before /builders/dom-utils.js — dom-utils must be the first hall script`;
+  if (/\b(defer|async)\b/.test(tags[at].tag)) return 'loads /builders/dom-utils.js with defer/async — scripts that run while the page parses would find no window.OTB';
+  if (tags.filter((t) => t.src === '/builders/dom-utils.js').length > 1) return 'loads /builders/dom-utils.js twice';
+  return null;
+}
+
+function checkOneHtmlEscaper({ root = REPO_ROOT } = {}) {
+  const violations = [];
+  let scanned = 0;
+  for (const r of SCAN_ROOTS) {
+    for (const abs of walk(path.join(root, r), [])) {
+      scanned++;
+      const relPath = path.relative(root, abs).split(path.sep).join('/');
+      if (ALLOWED.has(relPath)) continue;
+      const text = fs.readFileSync(abs, 'utf8');
+      const hits = findEscapeTables(text);
+      if (hits.length) {
+        violations.push(`${relPath}:${hits[0]} — a private HTML escaper (a quoted &lt; literal: an escape table). Use the shared one: `
+          + 'window.OTB.escapeHtml in the browser, escapeHtml from src/html-escape.js (or api.escapeHtml in a module) on the server.');
+      }
+      const fakes = findFakeDelegates(text, { browser: /^modules\/[^/]+\/public\//.test(relPath) });
+      if (fakes.length) {
+        violations.push(`${relPath}:${fakes[0]} — defines a local HTML escaper name that does not point at a shared escaper `
+          + '(a fallback like `(s) => String(s)` escapes nothing). Delegate to window.OTB.escapeHtml / api.escapeHtml / src/html-escape.js.');
+      }
+    }
+  }
+  const hallDir = path.join(root, 'modules', 'hall-ui', 'public');
+  let pages = 0;
+  for (const abs of walk(hallDir, []).filter((f) => f.endsWith('.html'))) {
+    pages++;
+    const problem = hallPageOrderProblem(fs.readFileSync(abs, 'utf8'));
+    if (problem) violations.push(`${path.relative(root, abs).split(path.sep).join('/')} — ${problem}`);
+  }
+  return {
+    name: 'one HTML escaper per side (task 1004876)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} code files hold no private escape table (allowed: ${[...ALLOWED.keys()].join(', ')}); `
+      + `${pages} hall pages load dom-utils.js first.`,
+  };
+}
+
+module.exports = { checkOneHtmlEscaper, findEscapeTables, findFakeDelegates, hallPageOrderProblem, ALLOWED };

package/scripts/bongos/fitness.js

@@ -523,7 +523,7 @@ const KERNEL_FILES = [
   'src/module-api.js',                    // the published doorway
   'src/modules.js',                       // the registry/resolver facade
   'src/module-seams.js',                  // the seam registry (ports/events/contributions)
-  'src/role-responsibilities.js',         // the owner's written role statements (task 1003732) — modules.js reads it; imports nothing
+  'src/role-responsibilities.js', 'src/html-escape.js', // owner's role statements (task 1003732) + THE server HTML escaper (task 1004876) — both import nothing
   'src/module-loader/loader.js',          // the disk loader (discover → validate → mount)
   'src/module-loader/manifest-schema.js', // the manifest validator
   'src/module-loader/semver.js',          // coreVersion compatibility
@@ -1371,6 +1371,7 @@ const CHECKS = [
   // Task 1003206 carved this file from 2,004 lines to ~1,350, so that toll is paid
   // and the check gets its own line back.
   require('./version-literal-guard.js').checkNoVersionLiterals,
+  require('./escape-helper-guard.js').checkOneHtmlEscaper, // task 1004876: ONE HTML escaper per side (dom-utils.js / src/html-escape.js), and hall pages load dom-utils first
   require('./dev-box-guard.js').checkNoDevBox, // task 1003899 / ADR 0346: the retired dev box stays out (its exemption list lives in that file)
   require('./control-manifest.js').checkControlsExist, // Check 21 — task 1003131: goal-1000076 controls assert their own existence (the ADR 0022 assurance-of-assurance)
   require('./routine-schedule.js').checkRoutineCadencesScheduled, // Check 25 — task 1003209: a routine that declares a cadence must have a scheduler firing it AT that period (ADR 0188)
@@ -1436,7 +1437,7 @@ module.exports = {
   scanForRawNul,
   checkVocabularyWall, VOCAB_ALLOW, VOCAB_CITATION, VOCAB_EXTS, vocabFilesToScan,
   checkGoalMembershipVocabulary, GOAL_VOCAB_SURFACE, checkGovernmentRenameIdentity, RENAME_IDENTITY_RE, checkPrelaunchVocabulary, PRELAUNCH_SURFACE, // 19c task 1003120, 19d task 1003152
-  runAll,
+  runAll, CHECKS, // CHECKS: so a test can prove a check is registered, not just written (task 1004876)
   resolvesToHostGame,
   checkCoreHostBoundary,
   checkClaudeMdBudget,

package/scripts/bongos/key-card.js

@@ -112,10 +112,7 @@ function renderMonospaceKeyCard(model) {
 }
 
 // ---- HTML renderer (the in-feed branded card) ---------------------------
-function esc(s) {
-  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) =>
-    ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
-}
+const { escapeHtml: esc } = require('../../src/html-escape'); // the one server escaper (task 1004876)
 function renderKeyCardHtml(model) {
   const m = model;
   const bg = 'var(--color-background-warning)';

package/scripts/bongos/review-sheet.js

@@ -24,9 +24,7 @@ const path = require('node:path');
 const { pathToFileURL } = require('node:url');
 const { spawn } = require('node:child_process');
 
-function escapeHtml(s) {
-  return String(s == null ? '' : s).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
-}
+const { escapeHtml } = require('../../src/html-escape'); // the one server escaper (task 1004876)
 
 // parseArgs — the flags above; `shots` keep their order. A --shot with no "="
 // is an error, not a guess: the caption and the path cannot be told apart.

package/scripts/bongos/start.js

@@ -268,7 +268,7 @@ function claimableTable(rows, rewardFromServer, goals) {
 // the same card every time, app-native. Falls back to the markdown card when
 // the client can't draw widgets. Design system: flat, 0.5px borders, CSS
 // theme vars (light/dark), Tabler icons, no emoji.
-const hesc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const { escapeHtml: hesc } = require('../../src/html-escape'); // the one server escaper (task 1004876); it also escapes '
 const jsq = (s) => String(s == null ? '' : s).replace(/\\/g, '\\\\').replace(/'/g, "\\'").replace(/\n/g, ' ');
 
 function miniBar(pct) {

package/scripts/bongos/status.js

@@ -223,7 +223,7 @@ function clabel(c) {
 // builder-start card (flat, 0.5px borders, CSS theme vars, Tabler icons, no
 // emoji); classes are `.st-*` so they can't collide with builder-start's `.bs-*`
 // or the ship card's `.cc-*`.
-const sesc = (s) => String(s == null ? '' : s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const { escapeHtml: sesc } = require('../../src/html-escape'); // the one server escaper (task 1004876); it also escapes '
 
 // A value going inside a single-quoted JS string inside an HTML attribute needs
 // BOTH escapes, in that order. Task ids are digits so the existing handlers get

package/scripts/gds/escape-helper-guard.js

@@ -0,0 +1,6 @@
+// scripts/gds/escape-helper-guard.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/escape-helper-guard.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'escape-helper-guard.js');

package/scripts/status-mirror-sync.js

@@ -49,6 +49,7 @@ const { execFileSync } = require('node:child_process');
 const REPO_ROOT = path.resolve(__dirname, '..');
 const SRC = path.join(REPO_ROOT, 'modules', 'status-ui', 'public');
 const { branding, clientBranding, applyBrandConditionals } = require('../src/branding');
+const { escapeHtml } = require('../src/html-escape');
 
 // Stamp instance-identity tokens into the mirror HTML. The off-box mirror is
 // served by a static Pages host, NOT the branding-injecting Node server — so this
@@ -64,9 +65,7 @@ function brandTokens(html, brand = {}, publicOrigin = '', buildersOrigin = '') {
   const cur = (brand.currency && brand.currency.label) || 'credits';
   const Cur = cur ? cur.charAt(0).toUpperCase() + cur.slice(1) : cur;
   const company = (brand.identity && brand.identity.company) || {};
-  const esc = (s) => String(s == null ? '' : s)
-    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+  const esc = escapeHtml; // the one server escaper (task 1004876)
   return applyBrandConditionals(html, { companyName: company.name, companySite: company.site, companyTagline: company.tagline })
     .split('{{worldName}}').join(esc(world))
     .split('{{productName}}').join(esc(product))

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

@@ -464,6 +464,7 @@ const MODULE_GLOBS = {
     'scripts/bongos/route-shadow-guard.js', 'scripts/bongos/routine-schedule.js',
     'scripts/bongos/seam-wiring-guard.js', 'scripts/bongos/skill-preflight.js',
     'scripts/bongos/test-path-guard.js', 'scripts/bongos/version-literal-guard.js', 'scripts/bongos/dev-box-guard.js',
+    'scripts/bongos/escape-helper-guard.js', // task 1004876
   
     // ADOPTED (task 1004111): the enforcement surfaces this module already IS.
     // install-git-hooks.js + scripts/bongos/hooks/ are the pre-push hook beside the

package/src/bongos/platform-visibility-gate.js

@@ -177,9 +177,8 @@ function relativeReturn(raw) {
   return raw === '/' ? null : raw;
 }
 
-function escAttr(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
+// The one server escaper (task 1004876); it also escapes ' , which this copy did not.
+const { escapeHtml: escAttr } = require('../html-escape');
 
 // The door. Self-contained on purpose (the pre-launch gate's shape): it is
 // served to someone who may not see the project, so it pulls no stylesheet, no

package/src/bongos/prelaunch-gate.js

@@ -180,9 +180,8 @@ function relativeReturn(raw) {
   return raw;
 }
 
-function escAttr(s) {
-  return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
-}
+// The one server escaper (task 1004876); it also escapes ' , which this copy did not.
+const { escapeHtml: escAttr } = require('../html-escape');
 
 // The form. Self-contained and token-free on purpose: it is served BEFORE the
 // visitor is allowed to see anything, so it must not pull the branding bundle,

package/src/bongos/routes/auth.js

@@ -44,11 +44,7 @@ const seams = require('../../module-seams');
 // the kernel logger directly; only MODULES go via api.logger (the doorway).
 const log = require('../logger').logger.child({ src: 'auth' });
 
-function escapeHtml(s) {
-  return String(s ?? '').replace(/[&<>"']/g, (c) => ({
-    '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;',
-  }[c]));
-}
+const { escapeHtml } = require('../../html-escape'); // the one server escaper (task 1004876)
 
 // Render a small standalone HTML page in the builders' hall palette. Used for
 // OAuth error branches so the visitor sees something coherent rather than a

package/src/bongos/serve-internal.js

@@ -264,12 +264,8 @@ function dropEmptyHrefLinks(html, values) {
 // No token is ever emitted into a <script> or a CSS context (checked across
 // public-landing/, hall-ui/, status-ui/ — all under modules/ since task 1003322)
 // — that would need different escaping.
-// Ampersand first, or the other replacements get double-escaped.
-function esc(s) {
-  return String(s == null ? '' : s)
-    .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;').replace(/'/g, '&#39;');
-}
+// The one server escaper (src/html-escape.js, task 1004876).
+const { escapeHtml: esc } = require('../html-escape');
 // The instance apex origin from the full branding pack (domains is server-only,
 // so it never rides clientBranding). Best-effort so a branding hiccup can't crash
 // serving.

package/src/html-escape.js

@@ -0,0 +1,26 @@
+// src/html-escape.js — THE server-side HTML escaper (task 1004876, goal 1000135).
+//
+// Escapes the five characters that let text become markup — & < > " ' — so a
+// builder's own words (a task title, an error detail, a project name) stay text
+// when they are written into a page, an attribute or an email. null and
+// undefined render as empty text; anything else is String()-ed first.
+//
+// ONE copy per side, on purpose. The browser twin is window.OTB.escapeHtml in
+// modules/hall-ui/public/dom-utils.js and the two must agree on every input
+// (tests/html_escape.mjs runs both). Modules reach this one through the doorway
+// (`api.escapeHtml`, src/module-api.js — ADR 0083); core files and scripts
+// require it directly. scripts/bongos/escape-helper-guard.js fails fitness on a
+// third hand-rolled copy anywhere in the code.
+//
+// Zero dependencies by design: the CLI requires it, so it must cost nothing to load.
+
+'use strict';
+
+const TABLE = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+/** HTML-escape `s` for text or a quoted attribute value. null/undefined → ''. */
+function escapeHtml(s) {
+  return String(s ?? '').replace(/[&<>"']/g, (c) => TABLE[c]);
+}
+
+module.exports = { escapeHtml };

package/src/module-api.js

@@ -57,6 +57,10 @@ const { buildInfo } = require('./build-info');
 // (`responsibilitiesFor` via src/modules.js, `ROLE_RESPONSIBILITIES` via
 // scripts/bongos/gen-role-responsibilities.js) were never flagged and this one was.
 const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibilities');
+// Eager and destructured for the same reasons: html-escape.js requires nothing.
+// escapeHtml is THE server-side HTML escaper (task 1004876) — a module renders
+// user text into a page through this, never through a private copy.
+const { escapeHtml } = require('./html-escape');
 
 // ---------------------------------------------------------------------------
 // CORE_VERSION — the version of THIS published surface (semver).
@@ -75,7 +79,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.181'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.22.1'; // 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');
@@ -122,6 +126,10 @@ function logger(moduleKey) {
 module.exports = {
   CORE_VERSION,
 
+  // escapeHtml(s) — the one server-side HTML escaper (& < > " '; null → ''). The
+  //     browser twin is window.OTB.escapeHtml; fitness fails on a third copy (task 1004876).
+  escapeHtml,
+
   // --- auth & rank (ADR 0016) — the gates the loader composes around a module's
   //     routes; a module declares the rank it needs and never wires auth itself.
   get requireBuilder() { return require('./bongos/auth').requireBuilder; },

package/tests/blockers_kit_pager.mjs

@@ -22,7 +22,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
-import { makeRunner } from './helpers.mjs';
+import { makeRunner, realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const read = (rel) => fs.readFileSync(path.join(ROOT, rel), 'utf8');
@@ -97,7 +97,7 @@ function harness({ total = 57, failAfter = null, perPagePref = null } = {}) {
       getItem: (k) => (store.has(k) ? store.get(k) : null),
       setItem: (k, v) => store.set(k, String(v)),
     },
-    OTB: { toast: (msg) => toasts.push(msg) },
+    OTB: { ...realOTB(), toast: (msg) => toasts.push(msg) },
     addEventListener() {},
     // loadViewer() calls this for GET /me; signed-out (401) keeps isReviewer()
     // false, which is fine for these paging tests — they don't inspect the

package/tests/blockers_page_ui.mjs

@@ -26,7 +26,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
-import { makeRunner, makeEl, walk } from './helpers.mjs';
+import { makeRunner, makeEl, walk, realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -114,7 +114,7 @@ async function boot(opts = {}) {
     getElementById(id) { return walk(root, (el) => (el.id === id ? el : null)); },
   };
   const windowObj = {
-    OTB: { toast: (m) => toasts.push(m) },
+    OTB: { ...realOTB(), toast: (m) => toasts.push(m) },
     OTBBlockersLib,
     OTBTaskDetail: { href: (id) => '/task/' + id },
     BongosClient: { createClient: () => api },

package/tests/core_move_notice.mjs

@@ -15,6 +15,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -233,6 +234,7 @@ function boot({ data, permissions = { 'core.pin.move': true }, stored = {} } = {
   };
   const location = { hostname: 'h', origin: 'https://h', pathname: '/', hash: '', assign() {}, replace() {} };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning: false } },
     BongosClient: { createClient: () => ({ request: (method, p, opts) => {
       requested.push({ method, p, body: opts && opts.body });
@@ -313,7 +315,7 @@ async function panel(data) {
   const el = () => ({ hidden: true, textContent: '', _html: '', dataset: {}, set innerHTML(v) { this._html = String(v); }, get innerHTML() { return this._html; }, querySelectorAll: () => [] });
   const els = new Map([['software-update-scroll', el()], ['su-body', el()], ['su-note', el()], ['settings-groups', el()]]);
   els.get('settings-groups').dataset.active = 'update';
-  const windowObj = { BongosClient: { createClient: () => ({ request: async () => ({ ok: true, status: 200, data }) }) }, OTB: { escapeHtml }, location: { assign() {} } };
+  const windowObj = { BongosClient: { createClient: () => ({ request: async () => ({ ok: true, status: 200, data }) }) }, OTB: { ...realOTB(), escapeHtml }, location: { assign() {} } };
   const sandbox = { window: windowObj, document: { getElementById: (id) => els.get(id) || null, addEventListener() {} }, console, setTimeout, Date, Math, URL, Promise, String, Number };
   vm.createContext(sandbox);
   vm.runInContext(PANEL_SRC, sandbox, { filename: 'settings-software-update.js' });

package/tests/core_update_banner.mjs

@@ -12,6 +12,7 @@ import path from 'node:path';
 import vm from 'node:vm';
 import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const require_ = createRequire(import.meta.url);
@@ -265,6 +266,7 @@ function boot({ permissions, update, status = 200, dismissed = null, provisionin
   };
   const location = { hostname: 'h', origin: 'https://h', pathname, hash: '', assign() {}, replace() {} };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning } },
     BongosClient: {
       createClient: () => ({

package/tests/core_upgrade_owner_door.mjs

@@ -23,6 +23,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -409,6 +410,7 @@ function boot({ provisioning, deployUrl, pathname = '/settings', hash = '', held
   const location = { hostname: 'h', origin: 'https://h', pathname, hash, assign() {}, replace() {} };
   const update = { running: '1.19.871', latest: '1.19.1033', behind: true, reading: 'ok' };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning } },
     BongosClient: {
       createClient: () => ({

package/tests/craft_mode.mjs

@@ -14,6 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -115,6 +116,7 @@ function boot({ craft = true, session = {}, store = {}, throws = false, optOut =
     removeItem: (k) => { if (throws) throw new Error('SecurityError'); delete obj[k]; },
   });
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: {} },
     BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
     matchMedia: (q) => ({ matches: narrow && /max-width: 640px/.test(q), addEventListener() {} }),

package/tests/craft_mode_nav.mjs

@@ -14,6 +14,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -90,6 +91,7 @@ function boot({ session = {}, perms = { 'board.vote.cast': true } } = {}) {
   const location = { hostname: 'h', origin: 'https://h', href: 'https://h/work', pathname: '/work', hash: '', search: '', assign() {}, replace() {}, reload() {} };
   const mk = (obj) => ({ getItem: (k) => (k in obj ? obj[k] : null), setItem: (k, v) => { obj[k] = String(v); }, removeItem: (k) => { delete obj[k]; } });
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     __BRANDING__: {}, __MODULES__: { enabled: { provisioning: true } },
     BongosClient: { createClient: () => ({ request: () => new Promise(() => {}) }) },
     matchMedia: () => ({ matches: false, addEventListener() {} }),
@@ -274,6 +276,7 @@ function bootTree({ mode = null, activeId = null } = {}) {
     addEventListener() {}, removeEventListener() {},
   };
   const windowObj = {
+    OTB: realOTB(), // the page loads dom-utils.js first (task 1004876)
     location: { search: '' }, matchMedia: () => ({ matches: false }),
     localStorage: mk({}), sessionStorage: mk(mode ? { 'hall-craft': mode } : {}),
   };

package/tests/craft_review_mode.mjs

@@ -13,6 +13,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const HALL = path.join(ROOT, 'modules/hall-ui/public');
@@ -77,7 +78,7 @@ function boot({ session = {}, store = {}, narrow = false } = {}) {
     dispatchEvent() { return true; },
   };
   const mk = (obj) => ({ getItem: (k) => (k in obj ? obj[k] : null), setItem: (k, v) => { obj[k] = String(v); }, removeItem: (k) => { delete obj[k]; } });
-  const window = { localStorage: mk(store), sessionStorage: mk(session), matchMedia: (q) => ({ matches: narrow && /max-width: 640px/.test(q) }), location: { search: '' } };
+  const window = { OTB: realOTB(), localStorage: mk(store), sessionStorage: mk(session), matchMedia: (q) => ({ matches: narrow && /max-width: 640px/.test(q) }), location: { search: '' } };
   const sandbox = { window, document, Promise, setTimeout, clearTimeout, CustomEvent: class { constructor(t, i) { this.type = t; Object.assign(this, i); } } };
   vm.createContext(sandbox);
   // "Loading" a script: the wall runs the REAL craft-review.js; the palette is a fake panel.
@@ -208,7 +209,7 @@ test('THE WALL is scribbled in CSS only, in ink alone, and stands still under re
 });
 
 test('craft-review.js draws six small sky doodles, each with its pen, the wide ones foldable', () => {
-  const sandbox = { window: {} };
+  const sandbox = { window: { OTB: realOTB() } };
   vm.createContext(sandbox);
   vm.runInContext(REVIEW, sandbox);
   const api = sandbox.window.OTBCraftReview;

package/tests/criterion_ref_status.mjs

@@ -194,8 +194,13 @@ test('a slug carrying an apostrophe cannot break the click handler', () => {
   // single-quoted JS string inside an HTML attribute.
   const odd = { ...crit(2, "o'hara-rule", '1000999') };
   const html = status.renderStatusWidget({ ...DATA, criteria: [odd] }, null);
-  assert.ok(html.includes("sendPrompt('/status o\\'hara-rule')"),
-    'the apostrophe was not escaped for the JS string');
+  // The attribute is HTML-escaped AFTER the JS escape, so the apostrophe arrives as
+  // \' (task 1004876: the shared escaper escapes ' too) — the browser decodes the
+  // attribute first, and the JS it then parses is the \' asserted below.
+  const onclick = html.match(/onclick="([^"]*o\\'hara-rule[^"]*)"/);
+  assert.ok(onclick, 'the apostrophe was not escaped for the JS string');
+  assert.ok(onclick[1].replace(/'/g, "'").includes("sendPrompt('/status o\\'hara-rule')"),
+    'the decoded handler carries the JS-escaped apostrophe');
 });
 
 console.log(`\ncriterion ref — read side (task 1004069): ${passed} passed, ${failed} failed`);

package/tests/curve_kind_overlay.mjs

@@ -26,12 +26,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import vm from 'node:vm';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
 function loadKit() {
   const src = fs.readFileSync(path.join(ROOT, 'modules/hall-ui/public/hall-kit.js'), 'utf8');
-  const win = {};
+  const win = { OTB: realOTB() }; // the page loads dom-utils.js first (task 1004876)
   const ctx = vm.createContext({ window: win, document: { createElement: () => ({}) }, console });
   vm.runInContext(src, ctx);
   assert.ok(win.OTBKit, 'hall-kit.js did not publish window.OTBKit');

package/tests/founding_mode.mjs

@@ -13,6 +13,7 @@ import { createRequire } from 'node:module';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { realOTB } from './helpers.mjs';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
@@ -135,6 +136,13 @@ function makeHall() {
 
 // The REAL escaper and the real wake map are sliced out of shell.js with the function,
 // so the band's escaping is the shell's own, not a stand-in that agrees with the test.
+// shell.js escapes through window.OTB (dom-utils.js, task 1004876), so the window it is
+// handed carries the real one.
+function sliceEsc() {
+  const line = SHELL.split("\n").find((l) => l.startsWith("  function esc("));
+  assert.ok(line, "esc was located in shell.js");
+  return line;
+}
 function sliceFn(name) {
   const start = SHELL.indexOf('  function ' + name + '(');
   const end = SHELL.indexOf('\n  }\n', start);
@@ -145,8 +153,8 @@ function loadApplyFounding(document, access, brand = { identity: { productName:
   const wakeStart = SHELL.indexOf('  var WAKE_TEXT = {');
   const wakeEnd = SHELL.indexOf('};', wakeStart) + 2;
   assert.ok(wakeStart > -1, 'WAKE_TEXT was located in shell.js');
-  const src = [SHELL.slice(wakeStart, wakeEnd), sliceFn('esc'), sliceFn('applyFounding')].join('\n');
-  return new Function('document', 'brand', 'access', `${src}\nreturn applyFounding;`)(document, brand, access);
+  const src = [SHELL.slice(wakeStart, wakeEnd), sliceEsc(), sliceFn('applyFounding')].join('\n');
+  return new Function('document', 'brand', 'access', 'window', `${src}\nreturn applyFounding;`)(document, brand, access, { OTB: realOTB() });
 }
 
 const snapshot = (h) => JSON.stringify({