@bongos/core 1.19.272 → 1.19.274

package/docs/copy-registry.json

@@ -101,8 +101,8 @@
       "at": [
         "modules/hall-ui/public/goals-page.js:674",
         "modules/hall-ui/public/goals-page.js:926",
-        "modules/hall-ui/public/work.js:747",
-        "modules/hall-ui/public/work.js:812"
+        "modules/hall-ui/public/work.js:751",
+        "modules/hall-ui/public/work.js:821"
       ]
     },
     {
@@ -134,8 +134,8 @@
       "text": "Copy prompt",
       "occurrences": 3,
       "at": [
-        "modules/hall-ui/public/task.js:252",
-        "modules/hall-ui/public/task.js:269",
+        "modules/hall-ui/public/task.js:258",
+        "modules/hall-ui/public/task.js:275",
         "modules/hall-ui/public/work.js:446"
       ]
     },
@@ -179,8 +179,8 @@
       "occurrences": 3,
       "at": [
         "modules/hall-ui/public/goals-page.js:949",
-        "modules/hall-ui/public/work.js:783",
-        "modules/hall-ui/public/work.js:836"
+        "modules/hall-ui/public/work.js:792",
+        "modules/hall-ui/public/work.js:845"
       ]
     },
     {
@@ -385,7 +385,7 @@
       "occurrences": 2,
       "at": [
         "modules/hall-ui/public/goals-page.js:677",
-        "modules/hall-ui/public/work.js:750"
+        "modules/hall-ui/public/work.js:754"
       ]
     },
     {
@@ -775,7 +775,7 @@
       "occurrences": 2,
       "at": [
         "modules/hall-ui/public/profile.js:144",
-        "modules/hall-ui/public/work.js:905"
+        "modules/hall-ui/public/work.js:914"
       ]
     },
     {
@@ -795,7 +795,7 @@
       "occurrences": 2,
       "at": [
         "modules/hall-ui/public/goals-page.js:702",
-        "modules/hall-ui/public/work.js:954"
+        "modules/hall-ui/public/work.js:963"
       ]
     },
     {
@@ -915,7 +915,7 @@
       "occurrences": 2,
       "at": [
         "modules/hall-ui/public/goals-page.js:944",
-        "modules/hall-ui/public/work.js:828"
+        "modules/hall-ui/public/work.js:837"
       ]
     },
     {
@@ -1519,7 +1519,7 @@
       "surface": "builders-hall",
       "text": ", follow its acceptance criteria, stay within touches[], /builder-ship",
       "file": "modules/hall-ui/public/work.js",
-      "line": 735,
+      "line": 739,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2032,7 +2032,7 @@
       "surface": "builders-hall",
       "text": "Awaiting the grader / a confirmation before it can ship.",
       "file": "modules/hall-ui/public/task.js",
-      "line": 247,
+      "line": 253,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2311,7 +2311,7 @@
       "surface": "builders-hall",
       "text": "Checking dependency order…",
       "file": "modules/hall-ui/public/work.js",
-      "line": 696,
+      "line": 700,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -2320,7 +2320,7 @@
       "surface": "builders-hall",
       "text": "Checking for conflicts…",
       "file": "modules/hall-ui/public/work.js",
-      "line": 675,
+      "line": 679,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -2401,7 +2401,7 @@
       "surface": "builders-hall",
       "text": "Claimed {…} tasks. Open a terminal to start work.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 750,
+      "line": 754,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -2608,7 +2608,7 @@
       "surface": "builders-hall",
       "text": "Confirm that verification for #{…} actually passed?",
       "file": "modules/hall-ui/public/task.js",
-      "line": 284,
+      "line": 290,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -2743,7 +2743,7 @@
       "surface": "builders-hall",
       "text": "Copy prompt",
       "file": "modules/hall-ui/public/task.js",
-      "line": 252,
+      "line": 258,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -2752,7 +2752,7 @@
       "surface": "builders-hall",
       "text": "Copy prompt",
       "file": "modules/hall-ui/public/task.js",
-      "line": 269,
+      "line": 275,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -2950,7 +2950,7 @@
       "surface": "builders-hall",
       "text": "Could not load #{…}",
       "file": "modules/hall-ui/public/task.js",
-      "line": 303,
+      "line": 309,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -4147,7 +4147,7 @@
       "surface": "builders-hall",
       "text": "Goal #{…}",
       "file": "modules/hall-ui/public/task.js",
-      "line": 196,
+      "line": 202,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -4723,7 +4723,7 @@
       "surface": "builders-hall",
       "text": "Last claimed by",
       "file": "modules/hall-ui/public/task.js",
-      "line": 207,
+      "line": 213,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5560,7 +5560,7 @@
       "surface": "builders-hall",
       "text": "Not found",
       "file": "modules/hall-ui/public/task.js",
-      "line": 298,
+      "line": 304,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -5632,7 +5632,7 @@
       "surface": "builders-hall",
       "text": "Nothing in the backlog right now.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 944,
+      "line": 953,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5659,7 +5659,7 @@
       "surface": "builders-hall",
       "text": "Nothing shipped yet.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 905,
+      "line": 914,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5794,7 +5794,7 @@
       "surface": "builders-hall",
       "text": "Open task #{…}",
       "file": "modules/hall-ui/public/work.js",
-      "line": 954,
+      "line": 963,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -5839,7 +5839,7 @@
       "surface": "builders-hall",
       "text": "Open the Work Board",
       "file": "modules/hall-ui/public/task.js",
-      "line": 252,
+      "line": 258,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -6352,7 +6352,7 @@
       "surface": "builders-hall",
       "text": "Recent history could not be loaded right now.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 1043,
+      "line": 1052,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -6433,7 +6433,7 @@
       "surface": "builders-hall",
       "text": "Release your claim on #{…}? It returns to the queue and no {…} are earned.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 828,
+      "line": 837,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -6442,7 +6442,7 @@
       "surface": "builders-hall",
       "text": "Release {…}? {…} to the queue and no {…} are earned.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 777,
+      "line": 786,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -6460,7 +6460,7 @@
       "surface": "builders-hall",
       "text": "Released #{…}. It returns to the queue.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 783,
+      "line": 792,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -6469,7 +6469,7 @@
       "surface": "builders-hall",
       "text": "Released #{…}. It returns to the queue.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 836,
+      "line": 845,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -6937,7 +6937,7 @@
       "surface": "builders-hall",
       "text": "Select at least 2 waiting tasks to copy a parallel-session prompt.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 660,
+      "line": 664,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -6946,7 +6946,7 @@
       "surface": "builders-hall",
       "text": "Select at least 2 waiting tasks to copy a sequential prompt.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 685,
+      "line": 689,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -7090,7 +7090,7 @@
       "surface": "builders-hall",
       "text": "Ship it",
       "file": "modules/hall-ui/public/task.js",
-      "line": 243,
+      "line": 249,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -7099,7 +7099,7 @@
       "surface": "builders-hall",
       "text": "Shipped {…}{…}.",
       "file": "modules/hall-ui/public/task.js",
-      "line": 228,
+      "line": 234,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -7378,7 +7378,7 @@
       "surface": "builders-hall",
       "text": "Task #{…}",
       "file": "modules/hall-ui/public/task.js",
-      "line": 170,
+      "line": 176,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -7441,7 +7441,7 @@
       "surface": "builders-hall",
       "text": "Tasks are numbered separately from GitHub pull requests, so this may be a PR rather than a GDS task.",
       "file": "modules/hall-ui/public/task.js",
-      "line": 293,
+      "line": 299,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -7810,7 +7810,7 @@
       "surface": "builders-hall",
       "text": "The task list could not be loaded right now.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 1097,
+      "line": 1106,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -7828,7 +7828,7 @@
       "surface": "builders-hall",
       "text": "The work board failed to load. Reload to try again.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 1266,
+      "line": 1275,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -8089,7 +8089,7 @@
       "surface": "builders-hall",
       "text": "Try reloading in a moment.",
       "file": "modules/hall-ui/public/task.js",
-      "line": 303,
+      "line": 309,
       "origin": "js-markup",
       "confidence": "certain"
     },
@@ -8269,7 +8269,7 @@
       "surface": "builders-hall",
       "text": "Welcome, {…}. Claim and release tasks and follow work in progress — no terminal needed.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 1034,
+      "line": 1043,
       "origin": "js-text-assign",
       "confidence": "certain"
     },
@@ -8566,7 +8566,7 @@
       "surface": "builders-hall",
       "text": "You claimed #{…}. Open a terminal to start work.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 747,
+      "line": 751,
       "origin": "js-notice",
       "confidence": "certain"
     },
@@ -8575,7 +8575,7 @@
       "surface": "builders-hall",
       "text": "You claimed #{…}. Open a terminal to start work.",
       "file": "modules/hall-ui/public/work.js",
-      "line": 812,
+      "line": 821,
       "origin": "js-notice",
       "confidence": "certain"
     },

package/modules/hall-ui/public/dom-utils.js

@@ -230,8 +230,48 @@
     return { label: label || stripMd(raw).slice(0, 80), detail };
   }
 
+
+  // ---- ADR 0116 error envelope (task 1002462) -------------------------------
+  //
+  // The server returns `{ error: { code, message, details } }` via res.fail().
+  // 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. That degrades into a wrong-but-plausible toast rather than a
+  // visible break, so no smoke test catches it — which is how the same defect
+  // survived independently across four hall surfaces (work.js, task.js, and
+  // hand-rolled copies in goals-page.js and task-detail.js).
+  //
+  // These live here, in the shared toolkit every hall page already loads first,
+  // so a fifth copy is never the easiest option. They take the RESPONSE BODY —
+  // callers pass `err.data` — and each accepts BOTH the envelope and the
+  // pre-envelope flat shape `{ error: 'CODE', ...fields }`, so an older server
+  // still maps. Pure: no DOM, no network, no page-specific behaviour (unlike the
+  // network helpers, which are deliberately NOT in this file).
+  function errCode(data) {
+    const e = data && data.error;
+    if (e && typeof e === 'object') return e.code || '';
+    if (typeof e === 'string') return e;
+    return (data && data.code) || '';
+  }
+  function errMessage(data) {
+    const e = data && data.error;
+    if (e && typeof e === 'object' && e.message) return e.message;
+    return (data && data.message) || '';
+  }
+  // Structured payload. Falls back to the BODY itself on the flat shape, where
+  // the extra fields (conflicts, failures, what_to_do) sat at the top level.
+  function errDetails(data) {
+    const e = data && data.error;
+    if (e && typeof e === 'object' && e.details && typeof e.details === 'object') return e.details;
+    // ALWAYS an object, so every caller can read `det.conflicts` with no type
+    // guard. A non-object body (a string, a number) would otherwise leak through
+    // and turn a detail read into undefined-or-worse at the call site.
+    return (data && typeof data === 'object') ? data : {};
+  }
+
   window.OTB = {
     escapeHtml, $, fmtNum, num, fmtInt, fmtCompact, fmtDate, rankLabel, toast, moduleOn,
+    errCode, errMessage, errDetails, // task 1002462 — ADR 0116 envelope readers
     contributeSettingsPanel, settingsPanels,
     contributeHallWidget, hallWidgets, hallWidgetIds,
     splitCriterion,

package/modules/hall-ui/public/task.js

@@ -21,7 +21,7 @@
   // builds through unchanged; result-mode ({ status, ok, data }) preserves control flow 1:1.
   const api = window.BongosClient.createClient({ baseUrl: '', credentials: 'same-origin', throwOnError: false });
   const AUTH_NEEDED = 'auth-needed';
-  const { escapeHtml, $, fmtDate } = window.OTB;
+  const { escapeHtml, $, fmtDate, errCode, errMessage } = window.OTB; // task 1002462: envelope readers
   const toast = (msg) => window.OTB.toast(msg, { duration: 2600 });
   const curLabel = () => (window.__BRANDING__ && window.__BRANDING__.currency && window.__BRANDING__.currency.label) || 'credits';
 
@@ -70,13 +70,19 @@
   // exactly those POST /tasks/:id/ship + /confirm can return. The server is the
   // authority (ADR 0016); the UI only surfaces the refusal.
   function friendlyActionError(status, data) {
-    switch (data && data.error) {
+    // task 1002462: read the ADR 0116 envelope. `data.error` is an OBJECT here,
+    // so every case fell through to the generic default and a precise lifecycle
+    // refusal ("not confirmed yet", "attestation required") rendered as
+    // "Could not complete that (409)".
+    switch (errCode(data)) {
       case 'task_not_confirmed':
         return 'That task can only be shipped once it is confirmed (its grade has landed).';
       case 'task_not_completed':
         return 'That task is not marked complete yet.';
       case 'verify_attestation_required':
-        return (data && data.message) || 'Confirm a verification task only after the verify actually passed.';
+        // The server's own sentence is the useful one — it names the task and the
+        // flag. It sits at error.message under the envelope, not data.message.
+        return errMessage(data) || 'Confirm a verification task only after the verify actually passed.';
       case 'rank_too_low_for_task':
       case 'INSUFFICIENT_RANK':
         return 'Your rank is not high enough for that action.';

package/modules/hall-ui/public/work.js

@@ -35,7 +35,7 @@
   // window.OTB toolkit (dom-utils.js, loaded first). Thin wrappers keep this
   // file's exact variants (date-only fmtDate; a 2200ms clearing toast).
   // fmtAgo / toAuth / getJSON / postJSON stay local below.
-  const { escapeHtml, $, fmtNum } = window.OTB;
+  const { escapeHtml, $, fmtNum, errCode, errDetails } = window.OTB; // task 1002462: envelope readers
   // Shared task-domain helpers (task 1002463). These lived in two copies here and
   // in the other board and had already drifted — goals-page.js had silently lost
   // friendlyBatchReason's MODULE_CONFLICT case. Destructured so every call site
@@ -468,14 +468,18 @@
   // Map the server's typed error code to a builder-readable line. The codes are
   // exactly those POST /claims and POST /claims/:id/resolve can return.
   function friendlyActionError(status, data) {
-    const code = data && data.error;
-    switch (code) {
+    // task 1002462: read the ADR 0116 envelope. `data.error` is an OBJECT, so the
+    // old `const code = data && data.error` compared a string to an object and
+    // EVERY case below fell through to the generic default — a wrong-but-plausible
+    // toast on every claim/release refusal.
+    const det = errDetails(data);
+    switch (errCode(data)) {
       case 'ALREADY_CLAIMED':
         return 'Someone else claimed that task first. The board will refresh.';
       case 'TASK_NOT_READY':
         return 'That task is no longer ready to be claimed.';
       case 'TOUCHES_CONFLICT': {
-        const titles = Array.isArray(data.conflicts) ? data.conflicts.map((c) => c.title).filter(Boolean) : [];
+        const titles = Array.isArray(det.conflicts) ? det.conflicts.map((c) => c.title).filter(Boolean) : [];
         return titles.length
           ? `That task overlaps an active claim: ${titles.join('; ')}. Wait for it to ship.`
           : 'That task overlaps another active claim. Wait for it to ship.';
@@ -487,7 +491,7 @@
       case 'INSUFFICIENT_RANK':
         return 'Your rank is not yet high enough for that task.';
       case 'newcomer_must_ship_first':
-        return data.what_to_do || 'Ship your current claim before opening another.';
+        return det.what_to_do || 'Ship your current claim before opening another.';
       case 'NOT_YOUR_CLAIM':
         return 'That claim is not yours to release.';
       case 'ALREADY_RESOLVED':
@@ -753,8 +757,13 @@
       await refreshLive();
     } catch (err) {
       if (err && err.message === 'redirecting to auth') return;
-      if (err.status === 409 && err.data && err.data.error === 'batch_failed') {
-        const failures = Array.isArray(err.data.failures) ? err.data.failures : [];
+      // task 1002462: same envelope defect — this tested `err.data.error === 'batch_failed'`
+      // against an object, so an all-or-nothing batch refusal rendered as the generic toast
+      // and the per-task reasons were dropped on the floor.
+      if (err.status === 409 && errCode(err.data) === 'batch_failed') {
+        const bdet = errDetails(err.data);
+        const failures = Array.isArray(bdet.failures) ? bdet.failures
+          : (Array.isArray(err.data && err.data.failures) ? err.data.failures : []);
         const lines = failures.map((f) => `#${f.task_id} (${friendlyBatchReason(f)})`);
         toast(lines.length
           ? `The batch could not be claimed — ${lines.join('; ')}.`

package/modules/lifecycle/est-advisory.js

@@ -0,0 +1,162 @@
+// modules/lifecycle/est-advisory.js — the ESTIMATE-SCALE advisory (task 1003148).
+//
+// THE HOLE. Nothing tells a task author that 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 — and it is 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, decision 0.100/n=76, refactor 0.120/n=62, spike 0.142/n=36).
+// That is not per-task noise. Authors write HUMAN-HOURS-shaped numbers for work an
+// agent does in minutes.
+//
+// pms_calibrated_minutes (migration 015) already divides by that median so
+// /builder-start and the optimizer show a sane figure. But the STORED number stays
+// wrong, nobody is ever told, and every newly-filed task re-adds the same error —
+// so the calibration is a permanent correction for a mistake with no feedback
+// loop. It also misleads humans directly: 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.
+//
+// This module closes the loop WITHOUT blocking anything: POST /tasks attaches the
+// verdict to its 201 body as `est_advisory`, and an in-scale estimate gets `null` —
+// silence. Deliberately NOT an auto-correction: silently rewriting the author's
+// number is worse than the current silence, because then nobody learns the scale
+// either. Show the figure, name the evidence, let the author decide.
+//
+// PURE core + FAIL-OPEN wrapper, exported so every branch is pinned by a DB-free
+// unit test. A module sibling, like ./goal-advisory.js — same contract.
+
+// WHY THIS IS AN ABSOLUTE DELTA AND NOT A RATIO — a design flaw my own test
+// caught, worth recording so it is not reintroduced. The calibration is a pure
+// scalar multiply, so submitted / (submitted x ratio) === 1 / ratio for EVERY
+// input. A ratio-based "how inflated is this?" test therefore returns the same
+// answer for a correct 9-minute estimate as for a wrong 600-minute one — it fires
+// on everything, which is the noise failure this advisory must avoid. (It did:
+// est=9 for a bug floored to calibrated=1 and read as "9x over".)
+//
+// So the trigger is whether the TRANSLATION IS MATERIAL: how many minutes the
+// author's number and the calibrated equivalent actually differ by. A 9-minute
+// estimate translates to ~1 (delta 8 — not worth a word); a 300-minute estimate
+// translates to 45 (delta 255 — worth saying out loud).
+//
+// AND BE PRECISE ABOUT THE FEEDBACK LOOP, because the tempting claim is false:
+// adopting the suggested value does NOT silence this for that task. The
+// calibration is a constant multiply, so the new number gets translated too. The
+// loop closes at the POPULATION level — pms_calibration_summary recomputes the
+// median from shipped rows, so as authors write agent-minutes the ratio itself
+// climbs toward 1.0 and the delta collapses for everyone at once. That is the
+// only mechanism that can actually retire this advisory, and it is why the
+// advisory reports the ratio and its sample size rather than a verdict.
+const MIN_MATERIAL_DELTA = 15;
+
+// TWO conditions, because the delta alone is partly a "large estimate" detector:
+// with a mostly-corrected population (ratio 0.9) a 300-minute estimate still
+// differs by 30. This advisory is about SCALE, so it also requires the scale to
+// actually be off. Above this ratio, estimates and actuals broadly agree and there
+// is nothing to translate no matter how big the number is — which is what lets the
+// population feedback loop retire the advisory outright.
+const SCALE_OK_RATIO = 0.5;
+
+// Below this many samples for a kind, that kind's median is not worth quoting and
+// the overall median is used instead — mirroring pms_calibrated_minutes' own
+// thresholds (>=5 per kind, else >=10 overall) so the advisory and the calibration
+// can never disagree about which number applies.
+const MIN_KIND_SAMPLES = 5;
+const MIN_OVERALL_SAMPLES = 10;
+
+// PURE. Pick the median ratio that governs this kind, and say which population it
+// came from — the author should be able to tell "your kind, 214 samples" from
+// "everything, 1173 samples".
+function pickRatio({ kind, summary }) {
+  const rows = Array.isArray(summary) ? summary : [];
+  const forKind = rows.find((r) => r && r.kind === kind);
+  if (forKind && Number(forKind.sample_size) >= MIN_KIND_SAMPLES) {
+    const ratio = Number(forKind.median_ratio);
+    if (Number.isFinite(ratio) && ratio > 0) {
+      return { ratio, sample_size: Number(forKind.sample_size), basis: kind };
+    }
+  }
+  // Overall: a sample-weighted median is not reconstructible from per-kind medians,
+  // so use the median OF the per-kind medians weighted by nothing — an honest
+  // approximation, labelled as such. Callers that need the exact overall figure
+  // should read pms_calibration_summary() directly.
+  const usable = rows
+    .map((r) => ({ ratio: Number(r && r.median_ratio), n: Number(r && r.sample_size) }))
+    .filter((r) => Number.isFinite(r.ratio) && r.ratio > 0 && Number.isFinite(r.n) && r.n > 0);
+  const total = usable.reduce((s, r) => s + r.n, 0);
+  if (total < MIN_OVERALL_SAMPLES || usable.length === 0) return null;
+  const sorted = usable.map((r) => r.ratio).sort((a, b) => a - b);
+  const mid = Math.floor(sorted.length / 2);
+  const ratio = sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+  return { ratio, sample_size: total, basis: 'all kinds' };
+}
+
+// PURE, FAIL-OPEN. Returns null when there is nothing to say: no estimate given,
+// no usable history, or an estimate already in the right scale.
+function adviseEstimate({ estMinutes, kind, summary, taskId = null }) {
+  const est = Number(estMinutes);
+  if (!Number.isFinite(est) || est <= 0) return null; // nothing to judge
+  const picked = pickRatio({ kind, summary });
+  if (!picked) return null; // not enough history to make a claim
+  if (picked.ratio >= SCALE_OK_RATIO) return null; // the scale is fine — nothing to say
+  const calibrated = Math.max(1, Math.round(est * picked.ratio));
+  if (est - calibrated < MIN_MATERIAL_DELTA) return null; // translation immaterial — say nothing
+  const ratio = Math.round(picked.ratio * 1000) / 1000;
+  // The historical factor is a property of the KIND, not of this estimate — see
+  // the note on MIN_MATERIAL_DELTA. Report it as such rather than implying we
+  // measured this particular guess.
+  const kindFactor = Math.round((1 / picked.ratio) * 10) / 10;
+  return {
+    submitted_minutes: est,
+    calibrated_minutes: calibrated,
+    kind_factor: kindFactor,
+    median_ratio: ratio,
+    sample_size: picked.sample_size,
+    basis: picked.basis,
+    message: `est_minutes=${est} translates to ~${calibrated} min of real time. Across `
+      + `${picked.sample_size} shipped task(s) (${picked.basis}) the median actual/est ratio is `
+      + `${ratio}, i.e. estimates of this kind have run ~${kindFactor}x long — est_minutes is `
+      + 'AGENT-minutes, not human-hours. The calibration corrects the board, but the STORED number '
+      + 'is what a reader sees.',
+    next_step: taskId
+      ? `If ${calibrated} is closer, correct it: PATCH /tasks/${taskId} {"est_minutes": ${calibrated}}`
+      : `Consider est_minutes: ${calibrated}.`,
+  };
+}
+
+// The calibration population. Reads pms_calibration_summary() — the transparency
+// companion migration 015 shipped for exactly this — rather than recomputing the
+// medians, so this and pms_calibrated_minutes can never disagree about the ratio.
+// Lives HERE rather than in db.js: db.js is over the size ratchet's cap and this
+// is the only caller. The pool comes through the published module doorway.
+// Deliberately not fail-open — buildEstAdvisory below is the single failure site.
+async function calibrationSummary({ pool } = {}) {
+  const p = pool || require('../../src/module-api').getPool();
+  const { rows } = await p.query('SELECT kind, median_ratio, sample_size FROM pms_calibration_summary()');
+  return rows || [];
+}
+
+// The DB-touching wrapper. NON-BLOCKING BY CONSTRUCTION — any failure yields null
+// and the create still returns 201. Same contract as buildGoalAdvisory. `db` is
+// accepted for symmetry with that function and to let a test inject a summary.
+async function buildEstAdvisory({ db, task } = {}) {
+  try {
+    if (!task || task.est_minutes == null) return null;
+    const summary = (db && db.calibrationSummary) ? await db.calibrationSummary() : await calibrationSummary();
+    return adviseEstimate({
+      estMinutes: task.est_minutes,
+      kind: task.kind,
+      summary,
+      taskId: task.id,
+    });
+  } catch (e) {
+    // Through the published logger seam (api.logger), not a raw console call: a
+    // module logs via the doorway, and the console_call_count ratchet
+    // (config/fitness-baselines.json) holds at its recorded floor. Lazy-required
+    // so the DB-free unit test that exercises THIS branch stays hermetic.
+    require('../../src/module-api').logger('lifecycle')
+      .error('est-advisory (non-blocking)', e && e.message);
+    return null;
+  }
+}
+
+module.exports = { adviseEstimate, pickRatio, buildEstAdvisory, calibrationSummary, MIN_MATERIAL_DELTA, SCALE_OK_RATIO, MIN_KIND_SAMPLES, MIN_OVERALL_SAMPLES };