@bongos/core 1.22.2 → 1.23.1

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', 'src/html-escape.js', // owner's role statements (task 1003732) + THE server HTML escaper (task 1004876) — both import nothing
+  'src/role-responsibilities.js', 'src/html-escape.js', 'src/sleep.js', // owner's role statements (task 1003732) + THE server HTML escaper (task 1004876) + THE server sleep (task 1004893) — all 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
@@ -1365,13 +1365,12 @@ const CHECKS = [
   require('./doc-control-claims.js').checkDocControlClaims, // Check 37 — task 1003418 / audit A14: a doc cannot describe an enforcement control that does not exist (derived from the docs, not a hand list)
   require('./doc-cli-guard.js').checkDocNamesRealCli, // Check 22 — task 1003165 / G01: a doc that names a CLI invocation must match the real CLI
   require('./skill-preflight.js').checkOpsSkillsDeclareMachine, // Check 23 — task 1003167 / G03: an ops skill declares the machine it needs
-  // Check 24 — task 1003166 / G02: no ops script hardcodes a version id. It landed
-  // sharing Check 23's line, deliberately, because fitness.js was ~500 lines over
-  // the excess-lines ratchet and a new check could not afford one (idea 1000810).
-  // 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.
+  // Check 24 — task 1003166 / G02: no ops script hardcodes a version id. It once shared
+  // Check 23's line because fitness.js was over the excess-lines ratchet (idea 1000810);
+  // task 1003206 carved this file from 2,004 lines to ~1,350, so it has 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('./sleep-helper-guard.js').checkOneSleepHelper, // task 1004893: ONE sleep per side (dom-utils.js OTB.sleep / src/sleep.js)
   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)

package/scripts/bongos/local-preview.js

@@ -15,12 +15,13 @@
 // shipped. Set OTB_PREVIEW_PORT to override the default 3100.
 
 const lib = require('./local-preview-lib');
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 async function pollHealthy(ms = 20_000) {
   const end = Date.now() + ms;
   while (Date.now() < end) {
     if (await lib.health()) return true;
-    await new Promise((r) => setTimeout(r, 500));
+    await sleep(500);
   }
   return false;
 }

package/scripts/bongos/login.js

@@ -86,7 +86,7 @@ function prompt(q) {
   return new Promise((resolve) => rl.question(q, (a) => { rl.close(); resolve(String(a || '').trim()); }));
 }
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 // Run the device flow and return one of:
 //   { state: 'ok', token, builder } | { state: 'not_approved' } | { state: 'expired' }

package/scripts/bongos/page-reader.js

@@ -57,6 +57,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { spawn, spawnSync } = require('node:child_process');
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
 const INVENTORY_REL = 'docs/page-inventory.json';
@@ -511,7 +512,7 @@ async function renderOne(browser, kit, plan, base) {
     try { await kit.runActions(page, plan.actions); } catch (e) { notes.push(`${plan.state}: an action failed (${String(e.message).split('\n')[0].slice(0, 120)}); read as it stood`); }
     // A body read on a response from a page that has since navigated away never
     // settles, so the wait for the data is bounded.
-    await Promise.race([Promise.all(pending), new Promise((r) => setTimeout(r, 2000))]);
+    await Promise.race([Promise.all(pending), sleep(2000)]);
     const got = await page.evaluate(captureInPage);
     if (got.branding) collectStrings(got.branding, data);
     return { state: plan.state, strings: got.strings, notes, data };

package/scripts/bongos/probe-cache.js

@@ -38,6 +38,7 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const crypto = require('node:crypto');
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 // Default freshness. The probes this serves answer questions that change on a
 // deploy or a ship — minutes, not seconds — so 60s is generous for a session brief
@@ -156,7 +157,7 @@ const POLL_MS = 100;
 async function waitForRecord(file, ttlMs, now) {
   const deadline = Date.now() + WAIT_MS;
   while (Date.now() < deadline) {
-    await new Promise((r) => setTimeout(r, POLL_MS));
+    await sleep(POLL_MS);
     const rec = readRecord(file);
     if (isFresh(rec, ttlMs, now())) return rec;
     // The holder is gone and left nothing: stop waiting and do the work ourselves.

package/scripts/bongos/provision-core-upgrade.js

@@ -39,6 +39,7 @@ const { ensurePinWriteKey, hasOwnAccount, pinKeyPath, pinSshCommand } = require(
 const { replayPinCommit } = require('./provision-pin-replay.js'); // GitHub ahead → pin on top (task 1004733)
 const { isValidSlug } = require('../../modules/provisioning/provisioning.js');
 const { RELEASE_NOTES_FILE, RELEASE_NOTES_MAX_BYTES, parseChangeRecords, notesBetween } = require('./release-notes.js');
+const { sleep: sharedSleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 const outcome = require('./upgrade-outcome.js'); // how far a failed move got, as a class (task 1004446)
 
 // The shapes whose box this runner can actually reach. Mirrors UPGRADE_SHAPES in the
@@ -359,7 +360,7 @@ async function coreUpgradeInstance(inst, deps, intent) {
   // single immediate read races it binding its port. A false "did not take" here is
   // never cosmetic — it is what the owner is shown after the one act they were told they
   // could finally perform.
-  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep = deps.sleep || sharedSleep;
   let served = null;
   for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
     const res = boxExec(versionCmd(inst), { allowFail: true });

package/scripts/bongos/provision.js

@@ -57,6 +57,7 @@ const { capacityPreflight, statusCapacityLine } = require('./provision-capacity.
 const { installedCoreVersion, runnerBanner } = require('./runner-drift.js');
 const { teardownInstance } = require('./provision-teardown.js');
 const { disconnectInstance } = require('./provision-disconnect.js');
+const { sleep: sharedSleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 const { coreUpgradeInstance, preflightCoreUpgrade, snapshotAllCoreVersions } = require('./provision-core-upgrade.js'); // the owner's deploy door, ADR 0293
 const { isByoHost, recordByoHost } = require('./provision-byo-host.js'); // stand up NOTHING for a byo-host row, ADR 0323
 
@@ -515,7 +516,7 @@ async function provisionInstance(inst, deps) {
   // budget on an instance that may simply be slow); the liveness overlay is
   // what tells the owner the truth.
   log('  [healthz] verify the instance answers');
-  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep = deps.sleep || sharedSleep;
   let healthy = null;                     // null = not observed (dry-run)
   const tries = apply ? 10 : 1;
   for (let i = 0; i < tries; i++) {
@@ -869,7 +870,7 @@ async function settingsApplyInstance(inst, deps) {
   // 7's rule); a loopback PASS proves the process, not the address — the
   // domain-scoped sweep earns that claim.
   log('  [healthz] verify the instance answers after the restart');
-  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep = deps.sleep || sharedSleep;
   let healthy = false;
   for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
     const res = boxExec(healthzCmd(inst), { allowFail: true });
@@ -959,7 +960,7 @@ async function restartInstance(inst, deps) {
   // false "down" is never cosmetic here: this instance is ALREADY flagged
   // unreachable, and a hasty verdict would tell the owner their restart failed.
   log('  [healthz] verify the instance answers after the restart');
-  const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const sleep = deps.sleep || sharedSleep;
   let healthy = false;
   for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
     const res = boxExec(healthzCmd(inst), { allowFail: true });
@@ -1113,7 +1114,7 @@ async function placeManifestCreds(inst, mrow, deps) {
   //    used to record a failure for a setup that had succeeded. The JSON answer lives
   //    at /api/bongos/healthz — the root /healthz says a plain "ok" (task 1004577).
   if (apply) {
-    const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const sleep = deps.sleep || sharedSleep;
     let authConfigured = false;
     for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
       const out = boxExec(authHealthzCmd(inst), { allowFail: true });

package/scripts/bongos/publish-integration-gate.js

@@ -38,6 +38,7 @@
 'use strict';
 
 const fs = require('node:fs');
+const { sleep: sharedSleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 const WORKFLOW_FILE = 'integration.yml';
 const DEFAULT_TIMEOUT_MIN = 12; // inside publish.yml's 20-minute job, leaving room to pack + publish
@@ -70,7 +71,7 @@ function runsUrl(repo, sha) {
 // touches the world is injectable for tests/publish_integration_gate.mjs.
 async function waitForIntegration({
   sha, repo, token, timeoutMs, intervalMs,
-  fetchImpl = globalThis.fetch, sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now,
+  fetchImpl = globalThis.fetch, sleep = sharedSleep, now = Date.now,
 }) {
   const deadline = now() + timeoutMs;
   let last = { verdict: 'wait', run: null, why: 'no read yet' };

package/scripts/bongos/render-api.js

@@ -31,6 +31,7 @@
 'use strict';
 
 const { JsonHttpApi, makeApiError } = require('./http-api-client');
+const { sleep: sharedSleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 const RENDER_API_BASE = 'https://api.render.com/v1';
 
@@ -184,7 +185,7 @@ class RenderApi extends JsonHttpApi {
 
   // Poll until a new database is 'available'. `sleepFn` lets tests drive it with no clock.
   async settlePostgres(postgresId, { tries = 60, sleepMs = 5000, sleepFn } = {}) {
-    const sleep = sleepFn || ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const sleep = sleepFn || sharedSleep;
     for (let i = 0; i < tries; i++) {
       const pg = await this.getPostgres(postgresId);
       if (pg.status === 'available') return pg;

package/scripts/bongos/sandbox-stage.js

@@ -26,6 +26,7 @@ const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
 const localPreview = require('./local-preview-lib');
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 // The default health URL waitHealthy probes when a caller supplies none; the
 // local context always passes its own (localPreview.healthUrl).
@@ -198,7 +199,7 @@ async function waitHealthy(deps = {}) {
     } catch (e) {
       lastErr = e.message;
     }
-    await new Promise((r) => setTimeout(r, deps.pollMs || HEALTH_POLL_MS));
+    await sleep(deps.pollMs || HEALTH_POLL_MS);
   }
   return { ok: false, reason: lastErr };
 }

package/scripts/bongos/seed-bongos-v1-idea-routing-tasks.js

@@ -25,7 +25,7 @@ const META_TASK = 1003059;      // this planning session's meta task — moved i
 const DISCORD_BUGS_IDEA = 1000771; // subsumed by R11; marked promoted against it
 const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 async function api(method, path, body, _tries = 0) {
   await sleep(400); // base throttle to stay under the per-IP rate limit
   const res = await fetch(`${BASE}/api/bongos${path}`, {

package/scripts/bongos/seed-bv1-profiles-tasks.js

@@ -21,7 +21,7 @@ const GOAL = 1000045;
 const SRC = 'planning-session';
 const H = { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' };
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 async function api(method, path, body, _tries = 0) {
   await sleep(400); // base throttle to stay under the per-IP rate limit
   const res = await fetch(`${BASE}/api/bongos${path}`, {

package/scripts/bongos/seed-bv2-ideator-surface-tasks.js

@@ -32,7 +32,7 @@ const CRIT = {
 
 const SPEC = 'Spec: `docs/specs/bongos-v2-ideator-surface.md` (final). Design of record: idea 1001072 + `docs/design/ideator-surface-direction.md`.';
 
-const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 async function api(method, path, body, _tries = 0) {
   await sleep(400); // base throttle to stay under the per-IP rate limit
   const res = await fetch(`${BASE}/api/bongos${path}`, {

package/scripts/bongos/session-eval.js

@@ -27,6 +27,7 @@ const wanderingPrefs = require('../../modules/builder-settings/wandering-prefs')
 // fitness scans (modules/sessions/CLAUDE.md, "NOT in this module").
 const { scoreAccessibility } = require('../../modules/sessions/accessibility');
 const { resolveDefaultVersion } = require('./version-select.js');
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 // ---- classification vocabularies -----------------------------------------
 
@@ -489,7 +490,7 @@ if (require.main === module) {
       candidates = (search.data && search.data.sessions) || [];
       if (candidates.length > 0 || attempt === maxAttempts) break;
       console.error(`search returned 0 candidates (attempt ${attempt}/${maxAttempts}) — retrying in 1500ms (possible stale read, #608)...`);
-      await new Promise((r) => setTimeout(r, 1500));
+      await sleep(1500);
     }
     // An empty corpus is an ANOMALY by default (stale read / upload gap), NOT a
     // clean "nothing to do" — refuse to write a misleadingly-empty report so the

package/scripts/bongos/setup.js

@@ -32,6 +32,7 @@ function statusOrigin() {
   return API_BASE;
 }
 const onboardingConfig = require('./onboarding-config');
+const { sleep } = require('../../src/sleep'); // the one shared sleep (task 1004893)
 
 const DRY_RUN = process.argv.includes('--dry-run');
 // --skip-keys mirrors the same flag on scripts/setup-builder.sh — when set,
@@ -586,7 +587,7 @@ async function main() {
   const deadline = Date.now() + expires_in * 1000;
   let pollInterval = interval * 1000;
   while (Date.now() < deadline) {
-    await new Promise((r) => setTimeout(r, pollInterval));
+    await sleep(pollInterval);
     const poll = await (await cliClient()).auth.postAuthDevicePoll({ body: { device_code } });
     // Admission gate (SR-19 / task #1000): a first-time GitHub account that an
     // Archon hasn't approved is refused (HTTP 403, state:'not_approved'). Print a

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

@@ -0,0 +1,88 @@
+// scripts/bongos/sleep-helper-guard.js — fitness check: ONE "wait N milliseconds"
+// helper per side (task 1004893, goal 1000135).
+//
+// WHY. ~27 files each hand-rolled a Promise around setTimeout to wait. That is
+// harmless on its own, but it is the copy-paste that task 1004876 found ~45 of for
+// the HTML escaper, where some copies had quietly drifted. They were collapsed onto
+// exactly two definitions:
+//
+//   browser  modules/hall-ui/public/dom-utils.js  → window.OTB.sleep
+//   server   src/sleep.js                          → sleep (modules reach it
+//                                                   through src/module-api.js)
+//
+// This check keeps it that way. It looks for the SHAPE, not a name: a Promise whose
+// resolver is handed straight to setTimeout is a sleep whatever the variable is
+// called, and inline copies with no name at all were half of what the audit found. A BLOCKING sleep (Atomics.wait —
+// merge-lock.js, rename-ledger-prose.js) has a different shape and is left alone:
+// it freezes the thread on purpose, and the shared helper cannot do that.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const { REPO_ROOT } = require('./fitness-lib.js');
+
+const ALLOWED = new Map([
+  ['modules/hall-ui/public/dom-utils.js', 'the shared BROWSER sleep (window.OTB.sleep)'],
+  ['src/sleep.js', 'the shared SERVER sleep (module-api sleep)'],
+  ['modules/ui-design/kit/render.js', 'its wait runs INSIDE the browser page via page.evaluate — the function is serialized, so it cannot reach either shared helper'],
+]);
+
+// Where code lives. Tests are out of scope: a test injects its own fake sleep.
+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']);
+
+// new Promise(<resolver> => [{] setTimeout(<same resolver>, …  — arrow or function form.
+const SLEEP_RE = /new\s+Promise\(\s*(?:function\s*)?\(?\s*(\w+)\s*\)?\s*(?:=>\s*)?\{?\s*setTimeout\(\s*(\w+)\s*,/g;
+
+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;
+}
+
+// findHandRolledSleeps(text) → 1-based line numbers holding a hand-rolled sleep.
+function findHandRolledSleeps(text) {
+  const lines = String(text).split('\n');
+  const hits = [];
+  for (let i = 0; i < lines.length; i++) {
+    for (const m of lines[i].matchAll(SLEEP_RE)) {
+      if (m[1] === m[2]) { hits.push(i + 1); break; }
+    }
+  }
+  return hits;
+}
+
+function checkOneSleepHelper({ 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 hits = findHandRolledSleeps(fs.readFileSync(abs, 'utf8'));
+      if (hits.length) {
+        violations.push(`${relPath}:${hits[0]} — a hand-rolled sleep (new Promise → setTimeout). Use the shared one: `
+          + 'window.OTB.sleep in the browser, sleep from src/sleep.js (or api.sleep in a module) on the server.');
+      }
+    }
+  }
+  return {
+    name: 'one sleep helper per side (task 1004893)',
+    ok: violations.length === 0,
+    hardFail: violations.length > 0,
+    violations,
+    warnings: [],
+    note: `${scanned} code files hold no hand-rolled sleep (allowed: ${[...ALLOWED.keys()].join(', ')}).`,
+  };
+}
+
+module.exports = { checkOneSleepHelper, findHandRolledSleeps };

package/scripts/bongos/upgrade.js

@@ -832,7 +832,7 @@ async function recordLedger({ fromVersion, toVersion, sourceCommit, note, reques
 // Connection-refused fails fast, so the early retries are cheap; the backoff caps at 2s.
 async function pollHealth(healthUrl, deps = {}) {
   const fetchImpl = deps.fetch || fetch;
-  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep = deps.sleep || require('../../src/sleep').sleep; // the one shared sleep (task 1004893)
   const now = deps.now || Date.now;
   const budgetMs = deps.healthBudgetMs != null ? deps.healthBudgetMs : 30_000;
   const deadline = now() + budgetMs;
@@ -882,7 +882,7 @@ function deriveVersionUrl(healthUrl) {
 // (a real failure) from "it wouldn't tell me" (unconfirmed), because only the first is proof.
 async function pollServedVersion(versionUrl, deps = {}) {
   const fetchImpl = deps.fetch || fetch;
-  const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep = deps.sleep || require('../../src/sleep').sleep; // the one shared sleep (task 1004893)
   const now = deps.now || Date.now;
   // Default to the health budget when a caller (or a test) has already narrowed it, else 15s.
   const budgetMs = deps.versionBudgetMs != null

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

@@ -0,0 +1,6 @@
+// scripts/gds/sleep-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/sleep-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, 'sleep-helper-guard.js');

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

@@ -465,6 +465,7 @@ const MODULE_GLOBS = {
     '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
+    'scripts/bongos/sleep-helper-guard.js', // task 1004893
   
     // 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/module-api.js

@@ -61,6 +61,8 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // 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');
+// sleep is THE server-side "wait N milliseconds" (task 1004893); sleep.js requires nothing.
+const { sleep } = require('./sleep');
 
 // ---------------------------------------------------------------------------
 // CORE_VERSION — the version of THIS published surface (semver).
@@ -79,7 +81,7 @@ const { escapeHtml } = require('./html-escape');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.22.2'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.23.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');
@@ -129,6 +131,9 @@ module.exports = {
   // 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,
+  // sleep(ms) — the one server-side "wait N milliseconds" (a Promise over setTimeout).
+  //     The browser twin is window.OTB.sleep; fitness fails on a third copy (task 1004893).
+  sleep,
 
   // --- 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.

package/src/sleep.js

@@ -0,0 +1,24 @@
+// src/sleep.js — THE server-side "wait N milliseconds" helper (task 1004893, goal 1000135).
+//
+// `await sleep(ms)` resolves to undefined after about `ms` milliseconds. It is a
+// plain global setTimeout under the hood, so it keeps setTimeout's forgiving
+// inputs (null, a numeric string, NaN all just mean "very soon") — which is why
+// it is not node:timers/promises, whose setTimeout throws on null or a string.
+//
+// ONE copy per side, on purpose. The browser twin is window.OTB.sleep in
+// modules/hall-ui/public/dom-utils.js. Modules reach this one through the doorway
+// (`api.sleep`, src/module-api.js — ADR 0083); core files and scripts require it
+// directly. scripts/bongos/sleep-helper-guard.js fails fitness on a third
+// hand-rolled copy. A BLOCKING sleep (Atomics.wait — merge-lock.js,
+// rename-ledger-prose.js) is a different tool and stays where it is.
+//
+// Zero dependencies by design: the CLI requires it, so it must cost nothing to load.
+
+'use strict';
+
+/** Resolve after about `ms` milliseconds. */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { sleep };

package/tests/deploy_page_projects.mjs

@@ -95,7 +95,8 @@ function boot({ controlPlane = preview('1', 'cloudbongos'), controlPlaneStatus =
   };
   const windowObj = {
     BongosClient: { createClient: () => ({ request }) },
-    OTB: { escapeHtml: (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c])), toast(m) { toasts.push(String(m)); } },
+    OTB: { escapeHtml: (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c])), toast(m) { toasts.push(String(m)); },
+      sleep: (ms) => new Promise((r) => setTimeout(r, ms)) }, // dom-utils' OTB.sleep (task 1004893)
     // `search` is what decides which project the page is about. A stub without it is the
     // shape the page has to survive, and the default here keeps that path exercised.
     location: { assign() {}, search: scope ? `?project=${encodeURIComponent(scope)}` : '', ...(href ? { href } : {}) },

package/tests/module_api.mjs

@@ -30,6 +30,7 @@ const PUBLISHED_SURFACE = [
   // published because the artist gate's one escape hatch is the owner's alone, and
   // a module cannot enforce that without being able to ask who the owner is.
   'getFoundingBuilder',
+  'sleep', // task 1004893: THE server-side "wait N milliseconds" (1.23.0) — modules wait through it, never a private copy
   'secretBox', // Gemini-key storage relocated to modules/art-pipeline + its 'art.getBuilderGeminiKeyRow' port (ADR 0102)
   'grantedScopeCoversRepos', // the create-route credential preflight's scope read (task 1002909); kernel (auth-config.js), unlike db/github-repos which the module reaches via `pool` + its own client
   'accountExistenceReadRateLimit', // task 1003339 (ADR 0209): the shared per-IP budget both account-existence probes spend from — one instance, not a factory, so the budget is genuinely shared

package/tests/sleep_helper.mjs

@@ -0,0 +1,99 @@
+// tests/sleep_helper.mjs — ONE "wait N milliseconds" helper per side (task 1004893, goal 1000135).
+//
+// ~27 files each hand-rolled `new Promise((r) => setTimeout(r, ms))`. They were
+// collapsed onto two: window.OTB.sleep (modules/hall-ui/public/dom-utils.js) in
+// the browser and sleep (src/sleep.js, re-exported by the module doorway as
+// api.sleep) on the server. The two blocking Atomics.wait sleeps
+// (modules/lifecycle/merge-lock.js, scripts/bongos/rename-ledger-prose.js) are a
+// different thing — they freeze the thread on purpose — and stay local. These
+// tests pin:
+//   1. the server sleep waits about as long as asked, and resolves to undefined;
+//   2. the module doorway hands modules the very same function;
+//   3. the browser twin exists on window.OTB and waits too;
+//   4. the fitness check goes red on a new hand-rolled copy and stays green on
+//      the repo, the two shared helpers and a blocking sleep.
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import vm from 'node:vm';
+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 PUB = path.join(ROOT, 'modules', 'hall-ui', 'public');
+
+const { sleep } = require('../src/sleep.js');
+const guard = require('../scripts/bongos/sleep-helper-guard.js');
+
+test('server sleep waits roughly the time asked and resolves to undefined', async () => {
+  const t0 = Date.now();
+  const v = await sleep(30);
+  assert.equal(v, undefined);
+  assert.ok(Date.now() - t0 >= 25, 'waited at least ~30ms');
+});
+
+test('server sleep keeps setTimeout\'s forgiving inputs (null, a numeric string) instead of throwing', async () => {
+  // node:timers/promises throws ERR_INVALID_ARG_TYPE on these; the hand-rolled copies never did.
+  await sleep(null);
+  await sleep('1');
+});
+
+test('the module doorway exports the shared server sleep', () => {
+  const api = require('../src/module-api.js');
+  assert.equal(api.sleep, sleep);
+});
+
+test('the browser twin is window.OTB.sleep and waits', async () => {
+  const sandbox = { window: {}, document: { querySelector: () => null }, setTimeout, Promise };
+  vm.createContext(sandbox);
+  vm.runInContext(fs.readFileSync(path.join(PUB, 'dom-utils.js'), 'utf8'), sandbox, { filename: 'dom-utils.js' });
+  const OTB = sandbox.window.OTB;
+  assert.equal(typeof OTB.sleep, 'function');
+  const t0 = Date.now();
+  await OTB.sleep(20);
+  assert.ok(Date.now() - t0 >= 15);
+});
+
+test('fitness: the repo holds no hand-rolled sleep outside the two shared helpers', () => {
+  const r = guard.checkOneSleepHelper();
+  assert.equal(r.ok, true, r.violations.join('\n'));
+});
+
+test('fitness: finds every shape of a hand-rolled sleep', () => {
+  const shapes = [
+    'const sleep = (ms) => new Promise((r) => setTimeout(r, ms));',
+    'const sleep = deps.sleep || ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));',
+    '    await new Promise(resolve => setTimeout(resolve, 3_000));',
+    '  sleep = (ms) => new Promise((r) => setTimeout(r, ms)), now = Date.now,',
+    'await Promise.race([a, new Promise((r) => setTimeout(r, 2000))]);',
+    'function sleep(ms) { return new Promise(function (res) { setTimeout(res, ms); }); }',
+  ];
+  for (const s of shapes) assert.deepEqual(guard.findHandRolledSleeps(s), [1], s);
+});
+
+test('fitness: a blocking Atomics.wait sleep and a timer that does real work are not flagged', () => {
+  assert.deepEqual(guard.findHandRolledSleeps('function sleepSync(ms) { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); }'), []);
+  assert.deepEqual(guard.findHandRolledSleeps('new Promise((r) => setTimeout(() => r(compute()), 10))'), []);
+  assert.deepEqual(guard.findHandRolledSleeps('const t = setTimeout(resolve, ms); t.unref();'), []);
+});
+
+test('fitness: goes red on a planted copy, green once it is gone', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 't1004893-'));
+  try {
+    fs.mkdirSync(path.join(tmp, 'scripts', 'bongos'), { recursive: true });
+    const f = path.join(tmp, 'scripts', 'bongos', 'x.js');
+    fs.writeFileSync(f, "const sleep = (ms) => new Promise((r) => setTimeout(r, ms));\n");
+    let r = guard.checkOneSleepHelper({ root: tmp });
+    assert.equal(r.ok, false);
+    assert.match(r.violations[0], /scripts\/bongos\/x\.js:1/);
+    fs.writeFileSync(f, "const { sleep } = require('../../src/sleep');\n");
+    r = guard.checkOneSleepHelper({ root: tmp });
+    assert.equal(r.ok, true, r.violations.join('\n'));
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});