@bongos/core 1.19.272 → 1.19.274

package/modules/lifecycle/routes/tasks.js

@@ -560,7 +560,7 @@ module.exports = function buildTasksRouter() {
       description: { type: 'string', maxLength: LIMITS.DESCRIPTION },
       status: { type: 'string', maxLength: 32 },
       touches: { type: 'array', maxItems: 500, itemsType: 'string' },
-      est_minutes: { type: 'integer', min: 0, max: 100000 },
+      est_minutes: { type: 'integer', min: 0, max: 100000 }, // AGENT-minutes — see est-advisory.js (task 1003148)
       est_cost_usd: { type: 'number', min: 0 },
       manual_degree: { type: 'integer', min: TASK_FIELD_BOUNDS.manual_degree.min, max: TASK_FIELD_BOUNDS.manual_degree.max },
       priority: { type: 'integer', min: TASK_FIELD_BOUNDS.priority.min, max: TASK_FIELD_BOUNDS.priority.max },
@@ -757,7 +757,7 @@ module.exports = function buildTasksRouter() {
         needs_migration: needsMigration,
         criteria,
         suggested_criteria,
-        goal_advisory,
+        goal_advisory, est_advisory: await require('../est-advisory').buildEstAdvisory({ db, task }), // task 1003148
       });
     } catch (err) {
       console.error('[gds] POST /tasks', err);

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.272",
+  "version": "1.19.274",
   "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/module-api.js

@@ -971,8 +971,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.270 with no explicit bump. run 32437463473. (task 1002620)
 //   1.19.272 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.271 with no explicit bump. run 32438140524. (task 1002620)
+//   1.19.273 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.272 with no explicit bump. run 32441024959. (task 1002620)
+//   1.19.274 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.273 with no explicit bump. run 32490024209. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.272'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.274'; // 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/est_advisory.mjs

@@ -0,0 +1,183 @@
+// tests/est_advisory.mjs — the estimate-SCALE advisory (task 1003148).
+//
+// THE HOLE. Nothing tells a task author their estimate is on the wrong SCALE.
+// Across 1,173 shipped tasks carrying both est_minutes and actual_minutes the
+// median actual/est ratio is 0.100, uniform across every kind with a real sample
+// (feature 0.078/n=489, bug 0.150/n=214, infra 0.097/n=144, cleanup 0.133/n=89).
+// Authors write human-hours-shaped numbers for work an agent does in minutes.
+//
+// pms_calibrated_minutes (migration 015) already divides by that median, so the
+// board looks sane while the STORED number stays wrong and every new task re-adds
+// the error — a permanent correction with no feedback loop. It misleads humans
+// directly too: GET /tasks/:id leads with the raw field, and a session quoted task
+// 1002572 to the owner as "60 min" when its calibrated value is 9.
+//
+// What we prove (PURE — no DB, no network):
+//   1. An out-of-scale estimate is flagged, with the calibrated equivalent, the
+//      ratio, and the SAMPLE SIZE it rests on — evidence, not an assertion.
+//   2. An in-scale estimate returns null. Silence is the common case; an advisory
+//      that fires on every create is noise and gets ignored.
+//   3. It never AUTO-CORRECTS. The submitted value is reported, not replaced —
+//      silently rewriting the author's number is worse than the current silence,
+//      because then nobody learns the scale either.
+//   4. The ratio source mirrors pms_calibrated_minutes' own thresholds (>=5 for a
+//      kind, else the overall population), so advisory and calibration can never
+//      disagree about which number applies — and it says WHICH basis it used.
+//   5. Missing / hostile / thin-sample input yields null, never a guess.
+//
+// Run:  node tests/est_advisory.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { adviseEstimate, pickRatio, buildEstAdvisory, MIN_MATERIAL_DELTA, SCALE_OK_RATIO } =
+  require('../modules/lifecycle/est-advisory.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { const r = fn(); if (r && r.then) return r.then(
+    () => { passed++; console.log(`  ok  ${name}`); },
+    (e) => { failed++; console.log(`  FAIL ${name}`); console.log(`     ${e.message}`); });
+    passed++; console.log(`  ok  ${name}`);
+  } catch (e) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${e.message}`); }
+  return Promise.resolve();
+}
+
+// The real shape pms_calibration_summary() returns, with the real medians.
+const SUMMARY = [
+  { kind: 'feature', median_ratio: '0.0780', sample_size: 489 },
+  { kind: 'bug', median_ratio: '0.1500', sample_size: 214 },
+  { kind: 'infra', median_ratio: '0.0970', sample_size: 144 },
+  { kind: 'cleanup', median_ratio: '0.1330', sample_size: 89 },
+  { kind: 'blocker-resolution', median_ratio: '0.1280', sample_size: 2 }, // below the kind floor
+];
+
+// ---- 1. the flag, with its evidence ----
+
+await t('an out-of-scale bug estimate is flagged with the calibrated equivalent', () => {
+  const a = adviseEstimate({ estMinutes: 60, kind: 'bug', summary: SUMMARY, taskId: 1002572 });
+  assert.ok(a, 'must advise');
+  assert.equal(a.submitted_minutes, 60);
+  assert.equal(a.calibrated_minutes, 9, '60 * 0.15 = 9 — the real number for task 1002572');
+  assert.equal(a.basis, 'bug');
+  assert.equal(a.sample_size, 214, 'quotes the sample the claim rests on');
+  assert.equal(a.median_ratio, 0.15);
+  assert.equal(a.kind_factor, 6.7, 'the historical factor is a property of the KIND');
+  assert.match(a.message, /AGENT-minutes/, 'names the unit, which is the actual defect');
+  assert.match(a.next_step, /PATCH \/tasks\/1002572 \{"est_minutes": 9\}/, 'gives the exact fix');
+});
+
+await t('the advisory reports, never auto-corrects', () => {
+  const a = adviseEstimate({ estMinutes: 300, kind: 'bug', summary: SUMMARY, taskId: 5 });
+  assert.equal(a.submitted_minutes, 300, 'the submitted value is preserved verbatim');
+  assert.equal(a.calibrated_minutes, 45);
+  // Nothing in the advisory mutates anything — it is a pure verdict object.
+  assert.equal(typeof a, 'object');
+  assert.ok(!('task' in a), 'no task payload — it cannot rewrite the row');
+});
+
+// ---- 2. silence is the common case ----
+
+await t('an already-agent-scale estimate returns null (no noise on a good create)', () => {
+  // The trigger is a MATERIAL translation, not a ratio — a ratio is constant by
+  // construction (see MIN_MATERIAL_DELTA) and would fire on correct estimates too.
+  assert.equal(adviseEstimate({ estMinutes: 9, kind: 'bug', summary: SUMMARY }), null,
+    '9 min for a bug is already agent-scale — translating it says nothing useful');
+  assert.equal(adviseEstimate({ estMinutes: 2, kind: 'bug', summary: SUMMARY }), null);
+  assert.equal(adviseEstimate({ estMinutes: 4, kind: 'feature', summary: SUMMARY }), null);
+});
+
+await t('the loop closes at the POPULATION level, not per task', () => {
+  // The tempting claim — "adopt the suggestion and it goes quiet" — is FALSE, and
+  // asserting it is how a wrong comment would have shipped. The calibration is a
+  // constant multiply, so the adopted value gets translated too:
+  const loud = adviseEstimate({ estMinutes: 300, kind: 'bug', summary: SUMMARY });
+  assert.ok(loud, 'a human-hours estimate is flagged');
+  assert.ok(adviseEstimate({ estMinutes: loud.calibrated_minutes, kind: 'bug', summary: SUMMARY }),
+    'adopting the value does NOT silence it — the multiplier re-applies');
+
+  // What DOES retire the advisory: the population correcting, which raises the
+  // median ratio toward 1.0 (pms_calibration_summary recomputes from shipped
+  // rows). Then even a large estimate translates to nearly itself.
+  const corrected = [{ kind: 'bug', median_ratio: '0.9500', sample_size: 400 }];
+  assert.equal(adviseEstimate({ estMinutes: 300, kind: 'bug', summary: corrected }), null,
+    'once estimates and actuals agree, the advisory has nothing to say — at ANY size');
+  assert.equal(adviseEstimate({ estMinutes: 5000, kind: 'bug', summary: corrected }), null,
+    'and size alone must never trigger it — this is a SCALE advisory, not a big-number one');
+  assert.ok(MIN_MATERIAL_DELTA > 0 && SCALE_OK_RATIO > 0 && SCALE_OK_RATIO < 1);
+});
+
+// ---- 3/4. which ratio, and why ----
+
+await t('pickRatio uses the KIND when it has enough samples, and says so', () => {
+  const p = pickRatio({ kind: 'feature', summary: SUMMARY });
+  assert.equal(p.basis, 'feature');
+  assert.equal(p.sample_size, 489);
+  assert.equal(p.ratio, 0.078);
+});
+
+await t('pickRatio falls back off a THIN kind rather than quoting 2 samples', () => {
+  // blocker-resolution has n=2, below the >=5 floor pms_calibrated_minutes uses.
+  const p = pickRatio({ kind: 'blocker-resolution', summary: SUMMARY });
+  assert.notEqual(p.basis, 'blocker-resolution', 'must not quote a 2-sample median as authority');
+  assert.equal(p.basis, 'all kinds');
+  assert.ok(p.sample_size > 900, 'the overall basis carries the whole population');
+});
+
+await t('an unknown kind still gets the overall basis', () => {
+  const p = pickRatio({ kind: 'nonexistent-kind', summary: SUMMARY });
+  assert.equal(p.basis, 'all kinds');
+});
+
+// ---- 5. fail closed ----
+
+await t('no estimate, no history, or hostile input ⇒ null, never a guess', () => {
+  assert.equal(adviseEstimate({ estMinutes: null, kind: 'bug', summary: SUMMARY }), null);
+  assert.equal(adviseEstimate({ estMinutes: 0, kind: 'bug', summary: SUMMARY }), null);
+  assert.equal(adviseEstimate({ estMinutes: -5, kind: 'bug', summary: SUMMARY }), null);
+  assert.equal(adviseEstimate({ estMinutes: 'sixty', kind: 'bug', summary: SUMMARY }), null);
+  // Thin overall population: nothing to claim.
+  assert.equal(adviseEstimate({ estMinutes: 600, kind: 'bug', summary: [{ kind: 'bug', median_ratio: '0.15', sample_size: 3 }] }), null);
+  assert.equal(adviseEstimate({ estMinutes: 600, kind: 'bug', summary: [] }), null);
+  assert.equal(adviseEstimate({ estMinutes: 600, kind: 'bug', summary: null }), null);
+  // Garbage rows must not crash or be trusted.
+  assert.equal(adviseEstimate({ estMinutes: 600, kind: 'bug', summary: [{ kind: 'bug', median_ratio: 'x', sample_size: 'y' }] }), null);
+});
+
+await t('buildEstAdvisory is NON-BLOCKING — a db failure yields null, not a throw', async () => {
+  const thrower = { calibrationSummary: async () => { throw new Error('pg down'); } };
+  assert.equal(await buildEstAdvisory({ db: thrower, task: { id: 1, kind: 'bug', est_minutes: 600 } }), null);
+  // No estimate on the task at all: nothing to judge, and no db call needed.
+  let called = false;
+  const spy = { calibrationSummary: async () => { called = true; return SUMMARY; } };
+  assert.equal(await buildEstAdvisory({ db: spy, task: { id: 1, kind: 'bug', est_minutes: null } }), null);
+  assert.equal(called, false, 'must not query when there is no estimate to judge');
+});
+
+await t('buildEstAdvisory returns the advisory on the happy path', async () => {
+  const db = { calibrationSummary: async () => SUMMARY };
+  const a = await buildEstAdvisory({ db, task: { id: 77, kind: 'feature', est_minutes: 90 } });
+  assert.ok(a);
+  assert.equal(a.calibrated_minutes, 7, '90 * 0.078 = 7');
+  assert.equal(a.basis, 'feature');
+  assert.match(a.next_step, /PATCH \/tasks\/77/);
+});
+
+await t('the route attaches est_advisory to the 201 body, non-blocking', () => {
+  // Mirrors the goal_advisory contract test. The call is folded into the response
+  // literal because modules/lifecycle/routes/tasks.js is over the size ratchet's
+  // cap and main sits exactly AT the baseline — so this feature had to land at
+  // net-zero lines in that file. Asserting the shape keeps the fold honest.
+  const src = fs.readFileSync(new URL('../modules/lifecycle/routes/tasks.js', import.meta.url), 'utf8');
+  const body201 = (src.match(/res\.status\(201\)\.json\(\{[\s\S]*?\}\);/) || [''])[0];
+  assert.ok(body201, 'found the 201 response body');
+  assert.match(body201, /est_advisory:/, 'est_advisory rides the create response');
+  assert.match(body201, /buildEstAdvisory\(\{ db, task \}\)/, 'and delegates rather than inlining logic');
+});
+
+console.log('');
+console.log(`est_advisory: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/goal_advisory.mjs

@@ -117,7 +117,12 @@ await test('db.js resolves the catch-all through generalGoalTitle — no second
 
 await test('the route delegates to buildGoalAdvisory in one line — no inline logic to drift', () => {
   assert.match(tasksSrc, /const goal_advisory = await buildGoalAdvisory\(\{ db, versionId: body\.version_id, task \}\);/);
-  assert.match(tasksSrc, /goal_advisory,\s*\}\);/, 'included in the 201 body');
+  // task 1003148: was /goal_advisory,\s*\}\);/ — it required goal_advisory to be
+  // the LAST key, which the sibling est_advisory broke. The assertion's intent is
+  // "present in the 201 body", so assert that, not the key order.
+  const body201 = (tasksSrc.match(/res\.status\(201\)\.json\(\{[\s\S]*?\}\);/) || [''])[0];
+  assert.ok(body201, 'found the 201 response body');
+  assert.match(body201, /goal_advisory,/, 'included in the 201 body');
 });
 
 // ---- buildGoalAdvisory: the real function, driven with a stub db ----

package/tests/hall_error_envelope.mjs

@@ -0,0 +1,264 @@
+// tests/hall_error_envelope.mjs — task 1002462.
+//
+// THE DEFECT. The server returns the ADR 0116 envelope via res.fail():
+// `{ error: { code, message, details } }`. The code is NESTED, so a bare
+// `data.error === 'CODE'` test compares a string to an OBJECT and silently never
+// matches — every switch falls through to its generic default. The builder gets
+// "Could not complete that (409). Try again." for a refusal the server described
+// precisely.
+//
+// It survived because it degrades into a wrong-but-PLAUSIBLE toast rather than a
+// visible break, so nothing failed and no smoke test could catch it. The same
+// defect appeared independently on four hall surfaces.
+//
+// The fix puts the readers in dom-utils.js — the shared toolkit every hall page
+// already loads first — so a fifth copy is never the easiest option.
+//
+// What we prove, executing the REAL files in a vm (the tests/hall_signout.mjs and
+// goal_criterion_confirm_ui.mjs precedent — there is no jsdom here):
+//   1. dom-utils' errCode / errMessage / errDetails read BOTH wire shapes and
+//      survive hostile input. This is now the single point of failure for four
+//      surfaces, so it is tested directly rather than through a page.
+//   2. END TO END on the real task.js: a 409 carrying the envelope renders the
+//      SERVER'S OWN sentence in the toast, not the generic fallback. This is the
+//      user-visible regression, driven through a real button click.
+//   3. Neither consumer still reads the flat shape anywhere.
+//
+// Run:  node tests/hall_error_envelope.mjs
+
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const HALL = path.join(ROOT, 'modules/hall-ui/public');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try {
+    const r = fn();
+    if (r && typeof r.then === 'function') {
+      return r.then(
+        () => { passed++; console.log(`  ok  ${name}`); },
+        (e) => { failed++; console.log(`  FAIL ${name}`); console.log(`     ${e.message}`); }
+      );
+    }
+    passed++; console.log(`  ok  ${name}`);
+  } catch (e) {
+    failed++; console.log(`  FAIL ${name}`); console.log(`     ${e.message}`);
+  }
+  return Promise.resolve();
+}
+
+// ---- 1. the shared readers, from the real dom-utils.js ----------------------
+
+function loadOTB() {
+  const sandbox = {
+    window: {},
+    document: {
+      createElement: () => ({ style: {}, classList: { add() {}, remove() {} }, appendChild() {}, remove() {} }),
+      body: { appendChild() {} },
+      querySelector: () => null,
+      querySelectorAll: () => [],
+      getElementById: () => null,
+    },
+    setTimeout, clearTimeout, console,
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(fs.readFileSync(path.join(HALL, 'dom-utils.js'), 'utf8'), sandbox, { filename: 'dom-utils.js' });
+  return sandbox.window.OTB;
+}
+
+await t('dom-utils exports the envelope readers on window.OTB', () => {
+  const OTB = loadOTB();
+  for (const fn of ['errCode', 'errMessage', 'errDetails']) {
+    assert.equal(typeof OTB[fn], 'function', `${fn} must be on the shared toolkit`);
+  }
+});
+
+await t('errCode reads the ADR 0116 envelope AND the legacy flat shape', () => {
+  const { errCode } = loadOTB();
+  assert.equal(errCode({ error: { code: 'ALREADY_CLAIMED', message: 'x' } }), 'ALREADY_CLAIMED');
+  assert.equal(errCode({ error: 'ALREADY_CLAIMED' }), 'ALREADY_CLAIMED', 'an older server must still map');
+  assert.equal(errCode({ code: 'ALREADY_CLAIMED' }), 'ALREADY_CLAIMED');
+});
+
+await t('errCode never returns an object — the whole bug in one assertion', () => {
+  const { errCode } = loadOTB();
+  const code = errCode({ error: { code: 'TOUCHES_CONFLICT', details: { conflicts: [] } } });
+  assert.equal(typeof code, 'string');
+  assert.notEqual(typeof code, 'object', 'returning the object is what made every switch case miss');
+});
+
+await t('errMessage prefers the envelope message over a top-level one', () => {
+  const { errMessage } = loadOTB();
+  assert.equal(errMessage({ error: { code: 'c', message: 'the real sentence' } }), 'the real sentence');
+  assert.equal(errMessage({ message: 'legacy sentence' }), 'legacy sentence');
+  assert.equal(errMessage({ error: 'c' }), '');
+});
+
+await t('errDetails takes error.details, else falls back to the BODY (flat shape)', () => {
+  const { errDetails } = loadOTB();
+  assert.deepEqual(errDetails({ error: { code: 'c', details: { conflicts: [{ title: 'A' }] } } }).conflicts, [{ title: 'A' }]);
+  // On the flat shape the extra fields sat at the top level.
+  assert.deepEqual(errDetails({ error: 'c', conflicts: [{ title: 'B' }] }).conflicts, [{ title: 'B' }]);
+});
+
+await t('the readers survive hostile / empty input without throwing', () => {
+  const { errCode, errMessage, errDetails } = loadOTB();
+  for (const bad of [undefined, null, {}, { error: null }, { error: 0 }, { error: [] }, 'str', 42]) {
+    assert.equal(typeof errCode(bad), 'string', `errCode(${JSON.stringify(bad)})`);
+    assert.equal(typeof errMessage(bad), 'string');
+    assert.equal(typeof errDetails(bad), 'object');
+  }
+});
+
+// ---- 2. end to end through the REAL task.js --------------------------------
+
+// Minimal DOM: only what task.js touches (getElementById/querySelector by id,
+// addEventListener, innerHTML, textContent). Elements are plain objects with a
+// click() that invokes the registered handler.
+// The DOM handlers call runLifecycle without returning its promise, so the toast
+// lands several microtasks after the click. Flush rather than guess a timeout.
+async function flush(n = 12) {
+  for (let i = 0; i < n; i += 1) await new Promise((r) => setImmediate(r));
+}
+
+function makeEl(id) {
+  return {
+    id, innerHTML: '', textContent: '', disabled: false, dataset: {}, style: {},
+    _handlers: {},
+    addEventListener(ev, fn) { this._handlers[ev] = fn; },
+    click() { return this._handlers.click && this._handlers.click(); },
+    querySelector: () => null,
+    querySelectorAll: () => [],
+    classList: { add() {}, remove() {}, toggle() {} },
+    setAttribute() {}, removeAttribute() {}, appendChild() {}, remove() {},
+  };
+}
+
+async function bootTaskPage({ task, failWith }) {
+  const els = new Map();
+  const el = (id) => {
+    const key = String(id).replace(/^#/, '');
+    if (!els.has(key)) els.set(key, makeEl(key));
+    return els.get(key);
+  };
+  const toasts = [];
+  const document = {
+    _ready: null,
+    // renderTask does document.title.split(' — ') — it must be a real string.
+    title: '#0 — task — Cloud Bongos',
+    addEventListener(ev, fn) { if (ev === 'DOMContentLoaded') this._ready = fn; },
+    getElementById: (id) => el(id),
+    querySelector: (sel) => el(sel),
+    querySelectorAll: () => [],
+    createElement: () => makeEl('tmp'),
+    body: makeEl('body'),
+  };
+  const sandbox = {
+    document,
+    console,
+    setTimeout,
+    clearTimeout,
+    location: { hostname: 'builders.example.com', pathname: `/task/${task.id}`, href: '', assign() {} },
+    window: {
+      OTBBranding: { taskCreditValue: () => null, taskCreditLabel: () => 'credits' },
+      confirm: () => true,
+      location: { hostname: 'builders.example.com', pathname: `/task/${task.id}`, assign() {} },
+      // The generated typed client's result mode: { status, ok, data }.
+      BongosClient: {
+        createClient: () => ({
+          request: async (method, urlPath) => {
+            if (method === 'GET' && urlPath.includes('/me')) {
+              return { ok: true, status: 200, data: { builder: { id: 1, rank: 'archon' } } };
+            }
+            if (method === 'GET') return { ok: true, status: 200, data: { task, last_claim: null } };
+            // The lifecycle POST — refuse it with the shape under test.
+            return { ok: false, status: failWith.status, data: failWith.body };
+          },
+        }),
+      },
+    },
+  };
+  sandbox.window.document = document;
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  // dom-utils FIRST, in this same context — exactly the real page's script order,
+  // and required because dom-utils' `$` closes over the document it sees at
+  // definition time.
+  vm.runInContext(fs.readFileSync(path.join(HALL, 'dom-utils.js'), 'utf8'), sandbox, { filename: 'dom-utils.js' });
+  const realToast = sandbox.window.OTB.toast;
+  sandbox.window.OTB = { ...sandbox.window.OTB, toast: (m) => { toasts.push(String(m)); } };
+  void realToast;
+  vm.runInContext(fs.readFileSync(path.join(HALL, 'task.js'), 'utf8'), sandbox, { filename: 'task.js' });
+  assert.ok(document._ready, 'task.js registered a DOMContentLoaded handler');
+  await document._ready();
+  return { els, el, toasts };
+}
+
+const VERIFY_TASK = { id: 4242, kind: 'verify', title: 'a verify task', status: 'completed', description: 'x' };
+
+await t('END TO END: a 409 envelope renders the SERVER\'S sentence, not the generic fallback', async () => {
+  const serverSentence = "Task #4242 is a verification task (kind='verify') — confirm it only AFTER the verification ran.";
+  const { el, toasts } = await bootTaskPage({
+    task: VERIFY_TASK,
+    failWith: {
+      status: 409,
+      body: { error: { code: 'verify_attestation_required', message: serverSentence, details: {} } },
+    },
+  });
+  const btn = el('confirm-btn');
+  assert.ok(btn._handlers.click, 'the confirm control rendered and is wired');
+  await btn.click();
+  await flush();
+  const shown = toasts.join(' | ');
+  assert.ok(
+    shown.includes(serverSentence),
+    `the toast must carry the server's own sentence. got: ${shown}`
+  );
+  assert.ok(
+    !/Could not complete that/.test(shown),
+    `the generic fallback is exactly the bug — got: ${shown}`
+  );
+});
+
+await t('END TO END: the legacy FLAT shape still maps (older server)', async () => {
+  const { el, toasts } = await bootTaskPage({
+    // status 'confirmed' + a supervisor is what renders the SHIP control.
+    task: { ...VERIFY_TASK, kind: 'feature', status: 'confirmed' },
+    failWith: { status: 409, body: { error: 'task_not_confirmed' } },
+  });
+  const btn = el('ship-btn');
+  assert.ok(btn._handlers.click, 'the ship control rendered');
+  await btn.click();
+  await flush();
+  const shown = toasts.join(' | ');
+  assert.match(shown, /only be shipped once it is confirmed/, `got: ${shown}`);
+  assert.ok(!/Could not complete that/.test(shown), `got: ${shown}`);
+});
+
+// ---- 3. no flat reads left in either consumer -------------------------------
+
+await t('neither work.js nor task.js reads the flat error shape any more', () => {
+  for (const rel of ['work.js', 'task.js']) {
+    const src = fs.readFileSync(path.join(HALL, rel), 'utf8');
+    const code = src.split('\n').filter((l) => !l.trim().startsWith('//')).join('\n');
+    assert.doesNotMatch(code, /data\s*&&\s*data\.error\b/, `${rel}: still reads data.error directly`);
+    assert.doesNotMatch(code, /err\.data\.error\s*===/, `${rel}: still compares err.data.error to a string`);
+    assert.doesNotMatch(code, /\bdata\.conflicts\b/, `${rel}: still reads conflicts off the body`);
+    assert.doesNotMatch(code, /\bdata\.what_to_do\b/, `${rel}: still reads what_to_do off the body`);
+    // And it must pull the shared readers rather than redefine a fifth copy.
+    assert.match(src, /window\.OTB/, `${rel}: uses the shared toolkit`);
+    assert.match(src, /errCode/, `${rel}: goes through errCode`);
+    assert.doesNotMatch(code, /function errCode\s*\(/, `${rel}: must NOT define its own copy`);
+  }
+});
+
+console.log('');
+console.log(`hall_error_envelope: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);