@bongos/core 1.19.309 → 1.19.311

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.309",
-  "core_contract": "1.19.309",
-  "source_commit": "725e32b7a94f36cdc81dd834470b1b66f526097a",
+  "core_version": "1.19.311",
+  "core_contract": "1.19.311",
+  "source_commit": "e1c43e441e7fc621f31480ab2306aa29cf6fabfa",
   "source_ref": "HEAD",
-  "built_at": "2026-08-23T20:35:56.294Z",
+  "built_at": "2026-08-23T20:49:01.750Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 322,
+    "docs_redacted": 323,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1420,
+    "functional_verbatim": 1421,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1764,
-  "tree_sha256": "3cc77df63f396bc4dd00a837f27e9ec425e865292ef87c68631cd21424c2b3a4",
+  "file_count": 1766,
+  "tree_sha256": "52b0f6698975b1156c233e14471c23249226712403aaad8498402f78a7a3c5d4",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1459,6 +1459,11 @@
       "mode": "0000644",
       "sha256": "9623542a240479c3ecec12dd0c9050d4b79b2791a414bc2cd6b05d99530a9c44"
     },
+    {
+      "path": "docs/design/demonolith-plan.md",
+      "mode": "0000644",
+      "sha256": "49b67aafae295e023be8583d668f1e3232c0d8ce18b8c0032c8fb77b347acd32"
+    },
     {
       "path": "docs/design/front-door-and-hub-direction.md",
       "mode": "0000644",
@@ -4577,12 +4582,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "773974cb943d497f52079b0a6c08f0847b26c1838ebbe19bc17c1d8dd645c014"
+      "sha256": "ac29f684d093a69db95b7e41ff40c70dccf70ea5a9bce2e78bf2a5b02ec302e7"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "55f105febecf217cd1bab4e0b599fea8440a9f4b7cde870d64d379777130e79e"
+      "sha256": "118f6dad272f412617ba4f4693317498f42580f7bb84cdca272705b3a696fe22"
     },
     {
       "path": "public-docs/index.html",
@@ -6122,7 +6127,7 @@
     {
       "path": "src/bongos/routes.js",
       "mode": "0000644",
-      "sha256": "4787e3b72334369d8d0a5c63bc97e19ef939782ec8fbc0d651dea543ad0dfbf7"
+      "sha256": "d0d7cd19a80e20946fa8d3ecdcb41f74871194d2c4e4518aeddc07a30e274630"
     },
     {
       "path": "src/bongos/routes/CLAUDE.md",
@@ -6132,7 +6137,7 @@
     {
       "path": "src/bongos/routes/_helpers.js",
       "mode": "0000644",
-      "sha256": "d838ae9082fa640bdf98f0d247d280e633af2150d1b0793708ce3fab166d8f05"
+      "sha256": "46ca1aee5960ea03c97c52de6ca246b06130185a7e2fe31fde79d117a6be29dc"
     },
     {
       "path": "src/bongos/routes/audit-log.js",
@@ -6252,7 +6257,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "568f4581ec3aaece8686d24935541d7a8783e8fbf0c9bb76b9fdf9be7150dff2"
+      "sha256": "c936d7dda32ef492b30f7b1230157e27d088606066056188794b0fd1b42f34f7"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6399,6 +6404,11 @@
       "mode": "0000644",
       "sha256": "39830ca32d20cfe1eab9a47c93c8f96866f4c04f13a98823d7c35b8383828ff9"
     },
+    {
+      "path": "tests/async_handler_500.mjs",
+      "mode": "0000644",
+      "sha256": "798f8c188f81d35361834954e7ffaed77cb771402bdb48866c98394fcbe26f32"
+    },
     {
       "path": "tests/atlas.mjs",
       "mode": "0000644",

package/docs/design/demonolith-plan.md

@@ -0,0 +1,105 @@
+# De-monolith plan — no first-party file over 1,500 lines
+
+**Date:** 2026-08-23 · **Task:** task 1003203 (spike, R03 of goal 1000079 "Code quality") · **Author:** example-owner
+**Feeds:** task 1003204 (db.js), task 1003205 (ship.js), task 1003206 (the rest), task 1003207 (dead-code/baselines)
+**Companion:** [`../audits/ai-dev-redteam-followup.md`](../audits/ai-dev-redteam-followup.md) §5
+
+---
+
+## The target
+
+Goal 1000079's `monoliths-eliminated` criterion (aggressive scope): **`oversized_file_count` → 0.** The ratchet ([`fitness-ratchets.js`](../../scripts/gds/fitness-ratchets.js)) counts tracked first-party `.js` files over **1,500 lines** (`OVERSIZE_LINES`), after excluding `node_modules/`, `public-docs/`, `*.min.js`, `redoc.standalone.js`, and `vendor/`. Baseline today: **12 files, `excess_lines_total` ≈ 12.3k.** Shrink-only — lower the baseline in [`config/fitness-baselines.json`](../../config/fitness-baselines.json) as each file drops under; never raise it.
+
+The 12 (current line counts on `main`):
+
+| # | File | Lines | Module | Decision | R-task |
+|---|---|---|---|---|---|
+| 1 | `modules/lifecycle/db.js` | 5,748 | lifecycle | **SPLIT** (7 seams) | 1003204 |
+| 2 | `scripts/gds/ship.js` | 4,613 | lifecycle | **SPLIT** (7 seams) | 1003205 |
+| 3 | `modules/hall-ui/public/builders.js` | 2,558 | hall-ui | **SPLIT** (3 seams) | 1003206 |
+| 4 | `scripts/gds/provision.js` | 2,498 | provisioning | **SPLIT** (4 seams) | 1003206 |
+| 5 | `modules/grading/grader.js` | 2,083 | grading | **SPLIT** (5 seams) | 1003206 |
+| 6 | `scripts/gds/fitness.js` | 1,990 | devsecops | **SPLIT** (checks→modules) | 1003206 |
+| 7 | `modules/hall-ui/public/goals-page.js` | 1,988 | hall-ui | **SPLIT** (extend existing carve) | 1003206 |
+| 8 | `scripts/gds/seed-v3-tasks.js` | 1,981 | (kernel) | **DELETE** (else allowlist) | 1003207 |
+| 9 | `modules/lifecycle/routes/tasks.js` | 1,884 | lifecycle | **SPLIT** (sub-routers) | 1003206 |
+| 10 | `src/bongos/auth.js` | 1,866 | kernel | **SPLIT** (4 seams) — highest risk | 1003206 |
+| 11 | `modules/lifecycle/routes/goals.js` | 1,535 | lifecycle | **SPLIT** (extend existing carve) | 1003206 |
+| 12 | `scripts/gds/box.js` | 1,519 | dev-box | **SPLIT** (2 seams — only 19 over) | 1003206 |
+
+**One rule above all:** these are structural moves, not rewrites. Every split preserves behaviour, the module boundary (a module reaches core only via `src/module-api.js`, never a core internal or another module), and the public port surface. A split that changes a contract is out of scope — file it separately.
+
+---
+
+## Per-file seams
+
+### 1. `db.js` → 7 seams (task 1003204) — highest coupling
+The lifecycle data layer, ~97 functions sharing one `withTx`/`seams` doorway. Split by domain, keeping the **state machine whole** and the **transaction-participant seams intact** (the claim/confirm/ship/grade/credit functions open the tx and call `resolveOptional('reward'|'onboarding')` inside it — ADR 0093 §2; do not sever a function from its tx). Candidate modules (rough sizes):
+- `db-rank-authz.js` (~450) — rank/permission/graduation: `claimPermissionsFor`, `rankAllowsTask`, `xenosClaimAllowed`, `_applyRankChangeTx`, `maybeAutoGraduateToThetes`, `syncGovernanceRankRole`, the grade-count SQL fragments.
+- `db-versions.js` (~150) — `listVersions`, `getVersion`, `versionProgress`, `createVersion`.
+- `db-goals.js` (~700) — goals + membership + criteria links + scope/visibility/successor/transfer.
+- `db-claims.js` (~600) — the claim refusal ladder, `claimTask`, `resolveClaim`, active-claims, release requests.
+- `db-tasks.js` (~700) — task CRUD, `createTask`, rescope, classifier hooks, dead-dep helpers.
+- `db-ship.js` (~700) — `confirmTask`/`shipTask`/`applyGrade` + criterion auto-close cascade (the tx-participant core).
+- `db-analytics.js` (~500) — estimation drift, grade trend, AI-dev curve, work-tracking reads; plus `tallyPeerVotes` + merge-lease (or a small `db-peer-votes.js`/`db-merge-lease.js`).
+- `db.js` remains a thin re-export/facade so `lifecycle.js` and existing requires keep working unchanged.
+**Risk: high.** Land behind the full lifecycle test suite (`coreB-carve-proof.sh` + the DB-integration tests named in the module CLAUDE.md); the boundary-forced duplications (`sealSessionLog`, `_applyRankChangeTx`, `gradePassCount`) must stay in lockstep with core.
+
+### 2. `ship.js` → 7 seams (task 1003205)
+Phases are the seams (its own doc says "search by phase keyword"):
+- `ship-surprise.js` — surprise/learning capture.
+- `ship-memory-sync.js` — memory sync-on-ship.
+- `ship-session-upload.js` — session digest + transcript upload + the ADR-0022 scrubber.
+- `ship-git.js` — git/shell/gh helpers, `buildMergeArgv`, `sanitizeGitHubRefs`.
+- `ship-deploy-target.js` — deploy-mode/target resolution.
+- `ship-grade.js` — the subagent-grader runner + baseline computation + grade formatting.
+- `ship-land.js` — merge/land/deploy orchestration + the ship card.
+- `ship.js` remains argv parsing + the phase orchestration (`main`). **Risk: medium** — pure CLI, no server tests, but it is the release path; smoke-test a real ship after.
+
+### 3. `builders.js` → 3 seams (task 1003206) — client JS
+IIFE attaching to `window.OTB`; extract to sibling `<script>` files that attach to the same namespace (no bundler): `ranks.js` (rank weight/normalize/badge — already mirrored per the source), `hall-widgets.js` (`ensureStandingGroups`/`widgetHost`/`mountHallWidgets`), leaving roster/table rendering in `builders.js`. **Risk: medium** (load-order in the page HTML).
+
+### 4. `provision.js` → 4 seams (task 1003206)
+`provision-db.js` (create/migrate/seed cmds), `provision-repo.js` (scaffold + repo auth + deploy keys + core-pin refresh), `provision-systemd.js` (service/backup/timer unit templates), `provision-env.js` (web.env body + federation). Keep `provision.js` as the intent-runner + `CONFIG`. **Risk: medium** (control-plane ops; unit-template tests exist).
+
+### 5. `grader.js` → 5 seams (task 1003206)
+`grader-prepass.js` (permission-path + route-rank deterministic pre-passes), `grader-model.js` (model selection), `grader-prompt.js` (prompt + context bundle), `grader-score.js` (validators, server-side guards, aggregation), `grader-subagent.js` (spawn/one-shot/cached). Keep `grader.js` as `gradeSubagent`/`gradeDeterministic` orchestration + the port surface. **Risk: medium.**
+
+### 6. `fitness.js` → checks-as-modules (task 1003206) — cleanest
+Already the pattern: `fitness-ratchets.js` and `control-manifest.js` are separate check modules registered here. Extend it — move check clusters to `fitness-checks-boundary.js`, `-docs.js`, `-migrations.js`, `-identity.js`; keep `fitness.js` as the `CHECKS` registry + runner. Each check is independent → low coupling. **Risk: low.**
+
+### 7. `goals-page.js` → extend the existing carve (task 1003206)
+Carve already begun (`goals-lib.js` per task 1003135, shared `hall-kit.js`). Finish it: move the remaining presentational helpers (`goalRenderFacts`, `goalRowHtml`, `goalCardHtml`, `statusBadge`, `goalStampHtml`) into `goals-lib.js`; keep the page as fetch/filter/render control flow. **Risk: low.**
+
+### 8. `seed-v3-tasks.js` → DELETE, else allowlist (task 1003207)
+81 task literals + 1 idempotent seeder function — pure historical data for GDS-V3, which has **shipped**. First choice: **delete** it (verify nothing requires it — it's an idempotent one-shot; `seed-gds-v4-tasks.js` is the sibling and also a candidate). If a reason to keep it surfaces, add a narrow, documented exclusion to `EXCLUDE_RE` for that specific file (not a blanket `seed-*.js` rule, which could hide a genuinely oversized seeder with logic). **Risk: low.**
+
+### 9. `routes/tasks.js` → sub-routers (task 1003206)
+~29 routes across clear resources. Split into `routes/tasks/{crud,dependencies,criteria,lifecycle,peer-votes,publish,overrides}.js`, each a function that registers its handlers on the shared router; `tasks.js` becomes the index that calls them. The two heavyweight handlers — `POST /tasks` (~220 lines) and `PATCH /tasks/:id` (~290 lines) — carry most of the bulk; their validation blocks can move to `task-write-validators.js`. **Risk: medium** (route tests exist; keep paths identical).
+
+### 10. `auth.js` → 4 seams (task 1003206) — HIGHEST RISK (kernel/protected)
+`auth-github.js` (OAuth creds/scopes, web + device flow, `fetchGithubUser`), `auth-idp.js` (federation hub assertion + logout token), `auth-discord.js` (Discord OAuth + guild membership), `auth-admission.js` (membership/admission/first-admin/rank-role sync). Keep `auth.js` as session-token mgmt + `extractTokens` + the middleware surface. **Risk: highest** — it is the identity path and a protected kernel file; land it last, behind the auth tests, with extra review. Sub-Metic builders may not touch it (behavioral rule).
+
+### 11. `routes/goals.js` → extend the existing carve (task 1003206)
+Already extracting (`goalSuggest.*`, `goalEdits.*` handlers imported). Continue: move the membership-request / invitation / members / conflicts / archive-reopen-scope-transfer handlers into `goal-*` helper modules the router wires up. **Risk: low–medium.**
+
+### 12. `box.js` → 2 seams (task 1003206) — only 19 lines over
+12 `cmd*` subcommands. Extract the two largest (`cmdProvision` ~300, `cmdReconcile*`) into `box-commands.js`; `box.js` stays the dispatcher. Trivial to get under 1,500. **Risk: low.**
+
+---
+
+## Ratchet exclusion-list update (for task 1003207)
+
+- **Do not** broaden `EXCLUDE_RE` to hide real code. The only content-based exclusion warranted is a **single-file** exception for `seed-v3-tasks.js` *if* it is kept rather than deleted (prefer deletion).
+- `redoc.standalone.js` / `public-docs/` / `*.min.js` / `vendor/` stay excluded (correct — vendored/generated).
+- As each file lands under 1,500, **lower** `oversized_file_count` and `excess_lines_total` in one PR with the extraction, so CI proves the drop.
+
+## Suggested sequencing (low-risk first, prove the loop)
+
+1. **box.js, fitness.js, goals-page.js, routes/goals.js** — low risk, existing carve patterns → immediate baseline drops, validates the ratchet-lowering flow.
+2. **seed-v3-tasks.js delete** — removes the largest single count with the least code risk.
+3. **routes/tasks.js, provision.js, grader.js, builders.js** — medium risk, module-local.
+4. **ship.js (1003205)** — medium risk, release path; smoke a real ship after.
+5. **db.js (1003204)** and **auth.js** — highest risk, land last, each behind its full test suite and (for auth.js) extra review.
+
+Every step is independently shippable and lowers the baseline — there is no big-bang cutover.

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.309",
+  "version": "1.19.311",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.309",
+      "version": "1.19.311",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.309",
+  "version": "1.19.311",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/bongos/routes/_helpers.js

@@ -343,6 +343,67 @@ function asyncHandler(tag, handler, { message = true, errorCode = 'server_error'
   };
 }
 
+// ── async-rejection hardening (task 1002673 / idea 1000475) ──────────────────
+//
+// Express 4 does NOT catch a rejected promise from an async handler: the
+// rejection never reaches next(err), the response is never written, and the
+// request hangs until the CDN gives up with a 524 (bug 1675 — a validator threw
+// on undefined.join() while BUILDING a 400 body, outside every try/catch).
+// errorEnvelopeHandler is already the trailing net for next(err); these two
+// functions are the missing conversion step. hardenRouterStack() runs ONCE at
+// the end of buildGdsRouter(), walks the fully-composed router (core routers +
+// loader-mounted module routers alike), and swaps every handler for a
+// promise-aware shim — so every current AND future route is covered without a
+// per-file sweep, and per-route context comes free from errorEnvelopeHandler's
+// method+originalUrl log line.
+//
+// Sync semantics are unchanged (Express already forwards a sync throw to
+// next(err)); error middleware (4-arg) is skipped because Express dispatches on
+// fn.length. The `_asyncHardened` marker makes the pass idempotent and is what
+// tests/async_handler_500.mjs walks to PROVE repo-wide coverage.
+function promiseSafeHandler(fn) {
+  if (typeof fn !== 'function' || fn._asyncHardened || fn.length >= 4) return fn;
+  const wrapped = function (req, res, next) {
+    try {
+      const out = fn.call(this, req, res, next);
+      if (out && typeof out.catch === 'function') out.catch((err) => next(err));
+      return out;
+    } catch (err) {
+      next(err);
+    }
+  };
+  Object.assign(wrapped, fn); // preserve any props a middleware factory attached
+  wrapped._asyncHardened = true;
+  try { Object.defineProperty(wrapped, 'name', { value: fn.name || 'promiseSafeHandler' }); } catch { /* cosmetic */ }
+  return wrapped;
+}
+
+// Recursively wrap every handler in a composed Express router: route-layer
+// handlers (router.<method>), plain middleware layers (router.use), and nested
+// routers (a mounted Router is a function carrying its own .stack). Returns the
+// number of functions wrapped. Mutates layer.handle in place — Express Layers
+// call `this.handle(…)`, so reassignment is the supported seam.
+function hardenRouterStack(router, seen = new Set()) {
+  const stack = router && router.stack;
+  if (!Array.isArray(stack) || seen.has(stack)) return 0;
+  seen.add(stack);
+  let wrapped = 0;
+  for (const layer of stack) {
+    if (layer.route && Array.isArray(layer.route.stack)) {
+      for (const rl of layer.route.stack) {
+        const next = promiseSafeHandler(rl.handle);
+        if (next !== rl.handle) { rl.handle = next; wrapped++; }
+      }
+    } else if (typeof layer.handle === 'function' && Array.isArray(layer.handle.stack)) {
+      wrapped += hardenRouterStack(layer.handle, seen); // nested Router
+    } else {
+      const next = promiseSafeHandler(layer.handle);
+      if (next !== layer.handle) { layer.handle = next; wrapped++; }
+    }
+  }
+  return wrapped;
+}
+
 // corsPublicGet — express middleware for the unauthenticated read-only public
 // surface (ADR 0029 / #566). The off-box status page reads these cross-origin.
 // Read-only, no-auth, no-secret routes, so a static '*' is safe; the caller
@@ -373,6 +434,8 @@ module.exports = {
   VALIDATION_REASONS,
   parseId,
   asyncHandler,
+  promiseSafeHandler,
+  hardenRouterStack,
   corsPublicGet,
   PAGINATION,
   parsePagination,

package/src/bongos/routes.js

@@ -65,6 +65,7 @@ const moduleLoader = require('../module-loader/loader');
 const { auditMiddleware } = require('./middleware/audit');
 const { rateLimitMiddleware } = require('./middleware/rate-limit');
 const { attachFail, errorEnvelopeHandler } = require('./middleware/error-envelope');
+const { hardenRouterStack } = require('./routes/_helpers');
 
 function buildGdsRouter() {
   const router = express.Router();
@@ -162,6 +163,14 @@ function buildGdsRouter() {
   // handler that already responded is untouched (res.headersSent short-circuits).
   router.use(errorEnvelopeHandler);
 
+  // Async-rejection hardening (task 1002673) — MUST run after every mount above.
+  // Walks the fully-composed stack (core + module routers) and swaps each handler
+  // for a promise-aware shim, so an async handler's rejection reaches next(err)
+  // and the errorEnvelopeHandler answers a fast, logged 500 instead of the
+  // request hanging until the CDN 524s (Express 4 does not do this itself).
+  // Error middleware (4-arg, incl. errorEnvelopeHandler) is skipped by design.
+  hardenRouterStack(router);
+
   return router;
 }
 

package/src/module-api.js

@@ -1045,8 +1045,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.307 with no explicit bump. run 32664559221. (task 1002620)
 //   1.19.309 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.308 with no explicit bump. run 32664868080. (task 1002620)
+//   1.19.310 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.309 with no explicit bump. run 32665109518. (task 1002620)
+//   1.19.311 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.310 with no explicit bump. run 32665535518. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.309'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.311'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/async_handler_500.mjs

@@ -0,0 +1,167 @@
+// tests/async_handler_500.mjs — async route rejections must 500 fast, never hang
+// (task 1002673 / idea 1000475; surfaced by bug 1675).
+//
+// THE BUG. Express 4 does not catch a rejected promise from an async route
+// handler: the rejection never reaches next(err), no response is written, and
+// the request hangs until the CDN gives up with a 524 — a mystery hang instead
+// of an obvious 500. The wild case threw on undefined.join() while building a
+// 400 body, OUTSIDE the handler's try/catch.
+//
+// THE FIX PINNED HERE. buildGdsRouter() ends with hardenRouterStack(router)
+// (src/bongos/routes/_helpers.js): every handler in the composed stack — core
+// routers, loader-mounted module routers, per-route middleware — is swapped for
+// a promise-aware shim that pipes a rejection into next(err), where the existing
+// errorEnvelopeHandler answers a logged 500 envelope. Error middleware (4-arg)
+// is skipped because Express dispatches on fn.length.
+//
+// COVERAGE PROOF (the task's done-when): rather than trusting a sweep, the last
+// test builds the REAL buildGdsRouter() and walks its full stack asserting every
+// handler is either shim-marked (_asyncHardened) or 4-arg error middleware — so
+// a future route added in ANY file is covered the moment it mounts, and this
+// test fails if the hardening call is ever dropped.
+//
+// Run:  node --test tests/async_handler_500.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import http from 'node:http';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const express = require('express');
+const { hardenRouterStack, promiseSafeHandler } = require('../src/bongos/routes/_helpers.js');
+const { attachFail, errorEnvelopeHandler } = require('../src/bongos/middleware/error-envelope.js');
+
+// Serve `app` on an ephemeral port, GET `path`, resolve { status, body, ms }.
+// The 3s timeout is the hang detector: an unhardened rejection never responds.
+function get(app, path, { timeoutMs = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const server = http.createServer(app);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      const t0 = Date.now();
+      const req = http.get({ host: '127.0.0.1', port, path }, (res) => {
+        let body = '';
+        res.on('data', (c) => { body += c; });
+        res.on('end', () => { server.close(); resolve({ status: res.statusCode, body, ms: Date.now() - t0 }); });
+      });
+      req.setTimeout(timeoutMs, () => { req.destroy(); server.close(); reject(new Error(`no response within ${timeoutMs}ms (hang)`)); });
+      req.on('error', (e) => { server.close(); reject(e); });
+    });
+  });
+}
+
+function appWith(router) {
+  const app = express();
+  app.use(attachFail);
+  app.use(router);
+  app.use(errorEnvelopeHandler);
+  return app;
+}
+
+test('a rejecting async handler answers a fast 500 envelope (not a hang) once hardened', async () => {
+  const router = express.Router();
+  router.get('/boom', async () => { throw new Error('kaboom: undefined.join()'); });
+  router.get('/late-boom', async (req, res) => {
+    await new Promise((r) => setTimeout(r, 10)); // reject after an await tick
+    throw new Error('late kaboom');
+  });
+  router.get('/fine', async (req, res) => { res.json({ ok: true }); });
+  const wrapped = hardenRouterStack(router);
+  assert.ok(wrapped >= 3, `expected all three handlers wrapped, got ${wrapped}`);
+
+  const app = appWith(router);
+  const boom = await get(app, '/boom');
+  assert.equal(boom.status, 500);
+  assert.ok(boom.ms < 2000, `must fail fast, took ${boom.ms}ms`);
+  const parsed = JSON.parse(boom.body);
+  assert.equal(parsed.error.code, 'internal_error');
+  assert.ok(!boom.body.includes('kaboom'), 'raw error message never leaks to the client');
+
+  const late = await get(app, '/late-boom');
+  assert.equal(late.status, 500);
+
+  const fine = await get(app, '/fine');
+  assert.equal(fine.status, 200);
+  assert.equal(JSON.parse(fine.body).ok, true);
+});
+
+test('control: the SAME rejecting handler without hardening hangs (proves the shim is load-bearing)', async () => {
+  // Runs in a CHILD process: the unhandled rejection is the bug itself, and the
+  // node:test runner in THIS process would (correctly) flag it. The child prints
+  // HANG when no response arrives within 1200ms — which is the expected outcome
+  // on Express 4 without the shim. If Express ever starts catching async
+  // rejections natively (v5), this prints RESPONDED and the shim is obsolete.
+  const { execFileSync } = await import('node:child_process');
+  const child = `
+    process.on('unhandledRejection', () => {}); // the bug: nothing else handles it
+    const express = require('express');
+    const http = require('http');
+    const app = express();
+    const router = express.Router();
+    router.get('/boom', async () => { throw new Error('unharnessed'); });
+    app.use(router);
+    const server = http.createServer(app);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      const req = http.get({ host: '127.0.0.1', port, path: '/boom' }, () => {
+        console.log('RESPONDED'); process.exit(0);
+      });
+      req.setTimeout(1200, () => { console.log('HANG'); process.exit(0); });
+      req.on('error', () => { console.log('HANG'); process.exit(0); });
+    });
+  `;
+  const out = execFileSync(process.execPath, ['-e', child], { encoding: 'utf8', timeout: 10_000 });
+  assert.match(out, /HANG/, 'unhardened async rejection should hang (if RESPONDED, Express now catches natively and the shim can retire)');
+});
+
+test('promiseSafeHandler: sync handlers and error middleware are untouched semantics', async () => {
+  // 4-arg error middleware must be returned as-is (Express dispatches on length).
+  const errMw = (err, req, res, next) => next(err);
+  assert.equal(promiseSafeHandler(errMw), errMw);
+  // Idempotent: a hardened fn is not re-wrapped.
+  const once = promiseSafeHandler(async () => {});
+  assert.equal(promiseSafeHandler(once), once);
+  // A sync throw still becomes a 500 through the same path.
+  const router = express.Router();
+  router.get('/sync-boom', () => { throw new Error('sync kaboom'); });
+  hardenRouterStack(router);
+  const res = await get(appWith(router), '/sync-boom');
+  assert.equal(res.status, 500);
+});
+
+test('REPO-WIDE PROOF: every handler in the real composed GDS router is hardened or error middleware', async () => {
+  const { buildGdsRouter } = require('../src/bongos/routes.js');
+  const router = buildGdsRouter();
+
+  let routeHandlers = 0;
+  let unhardened = [];
+  const seen = new Set();
+  const walk = (r, trail) => {
+    const stack = r && r.stack;
+    if (!Array.isArray(stack) || seen.has(stack)) return;
+    seen.add(stack);
+    for (const layer of stack) {
+      if (layer.route && Array.isArray(layer.route.stack)) {
+        for (const rl of layer.route.stack) {
+          routeHandlers++;
+          if (typeof rl.handle === 'function' && !rl.handle._asyncHardened && rl.handle.length < 4) {
+            unhardened.push(`${trail} ${Object.keys(layer.route.methods).join(',')} ${layer.route.path}`);
+          }
+        }
+      } else if (typeof layer.handle === 'function' && Array.isArray(layer.handle.stack)) {
+        walk(layer.handle, `${trail}>`);
+      } else if (typeof layer.handle === 'function') {
+        if (!layer.handle._asyncHardened && layer.handle.length < 4) {
+          unhardened.push(`${trail} [middleware ${layer.handle.name || 'anonymous'}]`);
+        }
+      }
+    }
+  };
+  walk(router, 'gds');
+
+  assert.ok(routeHandlers >= 250,
+    `expected the composed router to carry hundreds of route handlers, saw ${routeHandlers} — did module mounting break?`);
+  assert.deepEqual(unhardened, [],
+    `every handler must be async-hardened or 4-arg error middleware; naked: ${unhardened.slice(0, 10).join('; ')}`);
+});