@cohortapp/agent-sdk 2.4.1 → 2.5.0

package/scripts/daemon/cadence-handlers.mjs

@@ -626,12 +626,37 @@ function writeMessagingCursor(agentRoot, cursor) {
 }
 
 /**
- * messaging-inbound guard (guarded): poll the Cohort messaging/calling event
- * stream for new messages / @mentions / call-invites DIRECTED AT this
- * agent (lib/org/messaging.pullInbound), and ROUTE each one into the existing
- * daemon inbox pipeline by writing a legacy inbox item under
- * state/inbox/cohort/ — so the agent reacts to a Cohort @mention exactly like
- * a Slack/Telegram one (classifier → directed-gate → responder → dispatcher).
+ * messaging-inbound guard (guarded): poll the Cohort org event ledger for
+ * everything DIRECTED AT this agent and ROUTE each one into the existing daemon
+ * inbox pipeline by writing a legacy inbox item under state/inbox/cohort/ — so
+ * the agent reacts to a Cohort @mention exactly like a Slack/Telegram one
+ * (classifier → directed-gate → responder → dispatcher).
+ *
+ * ── WIDE, NOT messaging+calling (2026-08) ──
+ * This used to call `lib/org/messaging.pullInbound`, which pins
+ * `family=messaging,calling` on its events URL and recognises exactly two things
+ * (a message in a private room I am in, a call in one of my rooms). Every other
+ * surface hq emits — board/task, files & doc comments, decisions, escalations,
+ * approvals, handoffs, calendar, email — was read off the wire and thrown away,
+ * so a task assigned to this agent reached NOBODY: hq's in-process responder
+ * stands down for any member whose daemon beat inside 100s (hq 4d762d30) and
+ * the daemon was structurally deaf to the family.
+ *
+ * The live path is now `lib/org/inbound.pullWideInbound`, which returns the SAME
+ * `{events, nextCursor}` MessageEvent contract (plus `stats`), so everything
+ * below — eventToInboxItem, writeInboxItem, the cursor discipline — is unchanged.
+ *
+ * ADDRESSING STAYS ACL-SAFE. The org `/v1/events` feed is org-wide and REDACTED
+ * by design: a frame carries `mentionCount`, never the mentioned ids. The wide
+ * reader therefore never widens a payload; it resolves "is this for me" by
+ * JOINING the redacted frame against the agent's OWN entitled reads
+ * (`messaging.channels`, `messaging.history.mentions`, `board.context`,
+ * `approval.get`, `files.get`, `calendar.list`). A room this seat is not in is
+ * never paged, never hydrated, never delivered.
+ *
+ * Set MESSAGING_INBOUND_WIDE=0 to fall back to the old two-family reader (an
+ * operator escape hatch for an hq that is misbehaving on a family) — the
+ * fallback is LOGGED, never silent.
  *
  * The reactive daemon OWNS inbox dispatch, so the default decision is `inline`
  * (we route the items but don't escalate — escalating would double-respond, the
@@ -655,7 +680,20 @@ async function guardMessagingInbound({ event, agentRoot, log }, opts = {}) {
       return { ok: true, decision: "inline", cadence: event.cadence, reason: "org messaging not configured", routed: 0 };
     }
 
-    const pull = opts.pullImpl || (await import("../../lib/org/messaging.mjs")).pullInbound;
+    // WIDE by default. The narrow reader is kept reachable as an operator
+    // escape hatch, but taking it is a DEGRADATION and is logged as one.
+    const wide = process.env.MESSAGING_INBOUND_WIDE !== "0";
+    let pull = opts.pullImpl;
+    if (!pull) {
+      if (wide) {
+        pull = (await import("../../lib/org/inbound/index.mjs")).pullWideInbound;
+      } else {
+        pull = (await import("../../lib/org/messaging.mjs")).pullInbound;
+        if (typeof log === "function") {
+          log("warn", "[messaging-inbound] MESSAGING_INBOUND_WIDE=0 — using the narrow messaging+calling reader; board, task, calendar, escalation, approval, file and decision events WILL NOT arrive");
+        }
+      }
+    }
     const eventToInboxItem =
       opts.toInboxImpl || (await import("../../lib/channels/inbox-item.mjs")).eventToInboxItem;
     const writeInboxItem = opts.writeImpl || (await import("../poller/utils.mjs")).writeInboxItem;
@@ -671,28 +709,70 @@ async function guardMessagingInbound({ event, agentRoot, log }, opts = {}) {
       process.env.COHORT_AGENT_ID ||
       (cfg && cfg.org && cfg.org.cohort && cfg.org.cohort.agentId) ||
       undefined;
-    const res = await pull({ cfg, agentId, cursor, fetchImpl: opts.fetchImpl });
+    // Display names for prose-mention matching ("Isla, can you…" with no @).
+    // The wide reader only ever uses these to match text it was ALREADY entitled
+    // to read, so this cannot widen the aperture.
+    let myNames = opts.myNames;
+    if (myNames == null) {
+      try {
+        const { readIdentity } = await import("../../lib/org/registry.mjs");
+        const id = readIdentity(agentRoot) || {};
+        myNames = [id.firstName, id.fullName, id.preferredName].filter(
+          (n) => typeof n === "string" && n.trim(),
+        );
+      } catch { myNames = []; }
+    }
+
+    const res = await pull({
+      cfg,
+      agentId,
+      cursor,
+      fetchImpl: opts.fetchImpl,
+      myNames,
+      // The wide reader logs every degradation through this; without it a failed
+      // roster read, a capped page or a dropped hydration is invisible.
+      log: typeof log === "function" ? log : undefined,
+    });
     const events = (res && Array.isArray(res.events)) ? res.events : [];
 
     let routed = 0;
+    const failed = [];
     for (const ev of events) {
       try {
         const item = eventToInboxItem(ev);
         writeInboxItem("cohort", item, agentRoot);
         routed += 1;
-      } catch { /* one bad event must not drop the rest */ }
+      } catch (err) {
+        // One bad event must not drop the rest — but it must not vanish either.
+        // A silent catch here is exactly how six directed DMs went missing.
+        failed.push(`${(ev && ev.kind) || "?"}:${(ev && ev.message_id) || "?"} (${err && err.message ? err.message : String(err)})`);
+      }
+    }
+    if (failed.length && typeof log === "function") {
+      log("warn", `[messaging-inbound] ${failed.length} directed item(s) could NOT be written to the inbox: ${failed.slice(0, 5).join("; ")}`);
     }
 
     // Advance the cursor AFTER writing (at-least-once; writeInboxItem dedupes).
     const next = res && res.nextCursor != null ? res.nextCursor : cursor;
     if (next !== cursor) writeMessagingCursor(agentRoot, next);
 
-    if (routed && typeof log === "function") {
-      log("info", `[messaging-inbound] routed ${routed} Cohort item(s) into the inbox pipeline`);
+    // The wide reader hands back what it spent and what it dropped. Surfacing it
+    // is the difference between "the agent is quiet" and "the agent is deaf".
+    const stats = res && res.stats && typeof res.stats === "object" ? res.stats : null;
+    if (typeof log === "function") {
+      if (routed) {
+        const bySurface = stats && stats.bySurface
+          ? Object.entries(stats.bySurface).map(([k, v]) => `${k}×${v}`).join(", ")
+          : "";
+        log("info", `[messaging-inbound] routed ${routed} Cohort item(s) into the inbox pipeline${bySurface ? ` (${bySurface})` : ""}`);
+      }
+      if (stats && Array.isArray(stats.degraded) && stats.degraded.length) {
+        log("warn", `[messaging-inbound] DEGRADED facts this tick: ${stats.degraded.join(", ")} — directedness for those surfaces failed CLOSED (items may have been dropped)`);
+      }
     }
 
     if (process.env.MESSAGING_INBOUND_ESCALATE === "1" && routed > 0) {
-      return { ok: true, decision: "escalate", cadence: event.cadence, reason: `${routed} directed item(s)`, routed };
+      return { ok: true, decision: "escalate", cadence: event.cadence, reason: `${routed} directed item(s)`, routed, stats };
     }
     return {
       ok: true,
@@ -700,10 +780,19 @@ async function guardMessagingInbound({ event, agentRoot, log }, opts = {}) {
       cadence: event.cadence,
       reason: routed ? "routed to inbox (reactive-daemon-owns-dispatch)" : "no new directed items",
       routed,
+      wide,
+      stats,
       note: routed ? "Set MESSAGING_INBOUND_ESCALATE=1 to escalate instead of routing to the inbox." : undefined,
     };
   } catch (err) {
-    return { ok: true, decision: "inline", cadence: event.cadence, reason: "messaging-inbound-error", routed: 0, error: err && err.message ? err.message : String(err) };
+    // FAIL-OPEN IS FINE; SILENT IS NOT. A throw here means the agent received
+    // NOTHING this tick — the guard returning `ok:true` used to make that read
+    // as a healthy quiet org in every log and dashboard.
+    const message = err && err.message ? err.message : String(err);
+    if (typeof log === "function") {
+      log("error", `[messaging-inbound] pull FAILED (${message}) — 0 items routed this tick; nothing arrived from ANY surface`);
+    }
+    return { ok: true, decision: "inline", cadence: event.cadence, reason: "messaging-inbound-error", routed: 0, error: message };
   }
 }
 
@@ -943,17 +1032,69 @@ async function guardBrandSteward({ event, agentRoot, log }, opts = {}) {
  * @param {object} ctx - { event, agentRoot, log }
  * @param {object} [opts] - injectable seams: { runImpl, refreshImpl, cfg, enforcement, now, fetchImpl }
  */
+/** Keep ONLY the org credential. See the note at step 0 — a resolver's extra
+ *  keys (notably `agentRoot`) must never reach a deps bag by accident. */
+function credsOnly(c) {
+  return c ? { base: c.base || "", token: c.token || "", orgId: c.orgId || "" } : c;
+}
+
 async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
   const cadence = event && event.cadence ? event.cadence : "goal-steward";
   const say = typeof log === "function" ? log : () => {};
   try {
+    // 0. THE ORG CREDENTIAL. Everything below that talks to hq needs it, and
+    //    nothing here used to resolve it.
+    //
+    //    `refreshMandate`'s default callImpl is `lib/org/client.call(method,
+    //    params, {base, token, orgId})` — and `client.mjs` does NOT fall back to
+    //    the environment for `base`. Calling it with `{fetchImpl, log, now}`
+    //    (which is what this guard did) produced
+    //    `{ok:false, error:{code:"BAD_REQUEST", message:"missing base"}}` WITHOUT
+    //    a network round-trip, on every tick, forever. `fetchSnapshot` mapped
+    //    that to `call-failed:BAD_REQUEST` and `refreshMandate` fell back to the
+    //    local derivation — where every objective is `state:'proposed'`, which
+    //    compiles no obligations and admits no backlog.
+    //
+    //    Net effect, verified live: the goal-steward cadence had NEVER once read
+    //    an adopted mandate out of hq. It could not create a single item, and the
+    //    only symptom was one warn line that read like an outage.
+    // NARROWED to the three credential fields ON PURPOSE. `resolveOrgToolConfig`
+    // also returns `agentRoot` (its own resolution, which is NOT necessarily this
+    // cadence's root), and spreading the whole object into `runGoalSteward`
+    // silently re-pointed the loop at a different agent directory — it measured
+    // and would have written under the wrong root. Caught in the live run; never
+    // spread a resolver's output into a deps bag wholesale.
+    let conn = opts.conn === undefined ? undefined : credsOnly(opts.conn);
+    if (conn === undefined) {
+      try {
+        const { resolveOrgToolConfig } = await import("../../lib/org/tool-surface.mjs");
+        conn = credsOnly(resolveOrgToolConfig({ agentRoot, orgConfig: opts.cfg }));
+      } catch (err) {
+        conn = null;
+        say("error", `[goal-steward] could not resolve the org connection (${err && err.message ? err.message : err}) — the mandate cannot be refreshed and no sample can be mirrored to hq this tick`);
+      }
+    }
+    if (conn && (!conn.base || !conn.token)) {
+      say(
+        "warn",
+        `[goal-steward] no org credential for this seat (base=${conn.base ? "set" : "MISSING"} token=${conn.token ? "set" : "MISSING"}) — mandate.get and mandate.sample will both fail; the loop runs entirely on local state`,
+      );
+    }
+    const memberId = opts.memberId || (conn && conn.memberId) || process.env.COHORT_AGENT_ID || null;
+
     // 1. Refresh the mandate cache first — a goal loop running off a week-old
     //    mandate is worse than one that does not run. Fail-open: the loop's own
     //    staleness ladder is what actually decides what it may do.
     if (opts.refreshImpl !== null) {
       try {
         const refresh = opts.refreshImpl || (await import("../../lib/mandate/refresh.mjs")).refreshMandate;
-        const r = await refresh(agentRoot, { fetchImpl: opts.fetchImpl, log: say, now: opts.now });
+        const r = await refresh(agentRoot, {
+          ...(conn || {}),
+          memberId,
+          fetchImpl: opts.fetchImpl,
+          log: say,
+          now: opts.now,
+        });
         if (r && r.ok === false) {
           say("warn", `[goal-steward] mandate refresh failed (${r.reason}) — running on the cached mandate`);
         }
@@ -978,8 +1119,98 @@ async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
       }
     }
 
+    // 2b. THE SENSOR REGISTRY. Without this the loop measures nothing: every
+    //     objective's sensor lookup misses, `measureKpi` returns
+    //     {ok:false,"no-implementation"}, no sample is recorded, every gap is
+    //     null, and admission's honesty gate (source ∈ method|human) is
+    //     unsatisfiable by construction — D3 could not create a single item.
+    //     `reachableCapabilities` returns undefined (not an empty Set) when the
+    //     manifest is missing, so a broken manifest degrades to "measure without
+    //     the reachability check" instead of refusing every objective.
+    let sensors = opts.sensors;
+    let reachable = opts.reachable;
+    if (sensors === undefined || reachable === undefined) {
+      try {
+        const mod = await import("../../lib/kpi-sensors.mjs");
+        if (sensors === undefined) {
+          sensors = mod.buildSensorRegistry({ agentRoot, log: say, now: opts.now, fetchImpl: opts.fetchImpl });
+        }
+        if (reachable === undefined) reachable = mod.reachableCapabilities(agentRoot, { log: say });
+      } catch (err) {
+        say(
+          "error",
+          `[goal-steward] could not build the sensor registry (${err && err.message ? err.message : err}) — every objective will report no-implementation and NOTHING will be measured this tick`,
+        );
+      }
+    }
+
+    // 2c. THE RETURN LEG. `lib/goals/loop.mjs` calls `deps.mirrorSample` for
+    //     every sample it records, and hq implements the receiving end in full
+    //     (`src/server/methods/mandate/sample.ts`: server-decided `source`
+    //     honesty gate, `(orgId, objectiveId, window)` idempotency, gap
+    //     computation, chain append). `mirrorSample` had ZERO callers in either
+    //     repo — so every number this loop measured stayed on one laptop's disk
+    //     and hq's Objective.value / KpiSample series were never written by an
+    //     agent at all. The loop learned; the org did not.
+    //
+    //     `objectiveId` is hq's own row id, carried on the cached snapshot by
+    //     `projectObjective`. A locally-DERIVED objective has no id — those are
+    //     `state:'proposed'` and never reach here, but the guard is explicit
+    //     rather than sending a request hq would reject.
+    //
+    //     Best-effort by construction: the loop already wraps this in try/catch
+    //     and logs, and the local measurement is written BEFORE the mirror is
+    //     attempted, so an unreachable hq loses nothing.
+    let mirrorSample = opts.mirrorSample;
+    if (mirrorSample === undefined) {
+      if (!conn || !conn.base || !conn.token) {
+        mirrorSample = null;
+        say("warn", "[goal-steward] no org credential — measurements will be recorded LOCALLY ONLY and hq's KPI series will not move");
+      } else {
+        const { call } = await import("../../lib/org/client.mjs");
+        mirrorSample = async ({ objective, value, window, source, evidence }) => {
+          if (!objective || !objective.id) {
+            say("info", `[goal-steward] "${objective && objective.key}" has no hq objective id (locally-derived) — sample kept local`);
+            return;
+          }
+          const frame = await call(
+            "mandate.sample",
+            { objectiveId: objective.id, value, window, evidence: evidence || null },
+            { ...conn, fetchImpl: opts.fetchImpl },
+          );
+          if (!frame || !frame.ok) {
+            say(
+              "warn",
+              `[goal-steward] mandate.sample rejected "${objective.key}" @ ${window}: ${(frame && frame.error && frame.error.code) || "unknown"}${frame && frame.error && frame.error.message ? ` — ${frame.error.message}` : ""} — the local series is intact`,
+            );
+            return;
+          }
+          const got = frame.result || {};
+          // hq decides `source` itself and says so when it downgraded us. A
+          // silent downgrade is how a seat keeps reporting fabricated `method`
+          // samples forever without learning its sensor is not wired up.
+          if (got.sourceNote) {
+            say("warn", `[goal-steward] hq downgraded the sample source for "${objective.key}" (asked ${source}, got ${got.source}): ${got.sourceNote}`);
+          } else {
+            say("info", `[goal-steward] mirrored "${objective.key}" = ${value} @ ${window} to hq (source ${got.source || source})`);
+          }
+        };
+      }
+    }
+
     const run = opts.runImpl || (await import("../../lib/goals/loop.mjs")).runGoalSteward;
-    const report = await run({ agentRoot, log: say, enforcement, now: opts.now, ...(opts.runDeps || {}) });
+    const report = await run({
+      agentRoot,
+      log: say,
+      enforcement,
+      now: opts.now,
+      sensors,
+      reachable,
+      memberId,
+      ...(conn || {}),
+      ...(mirrorSample ? { mirrorSample } : {}),
+      ...(opts.runDeps || {}),
+    });
 
     if (!report || report.ok === false) {
       // Not an error for the bus: "no mandate" is the normal pre-adoption state.
@@ -998,6 +1229,7 @@ async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
     const rejected = (report.rejected || []).length;
     const escalations = (report.escalations || []).length;
     const drift = (report.drift || []).length;
+    const scored = (report.interventions || []).reduce((n, i) => n + (i.recorded || 0), 0);
 
     if (report.skipped) {
       return { ok: true, decision: "inline", cadence, reason: report.skipped, measured, admitted, drift };
@@ -1005,7 +1237,7 @@ async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
 
     say(
       "info",
-      `[goal-steward] ${enforcement}: measured ${measured}, admitted ${admitted}, rejected ${rejected}, escalations ${escalations}, drift ${drift}`
+      `[goal-steward] ${enforcement}: measured ${measured}, interventions scored ${scored}, admitted ${admitted}, rejected ${rejected}, escalations ${escalations}, drift ${drift}`
     );
 
     // 3. Escalate only when a model would actually add something: an open gap
@@ -1025,7 +1257,7 @@ async function guardGoalSteward({ event, agentRoot, log }, opts = {}) {
       };
     }
 
-    return { ok: true, decision: "inline", cadence, measured, admitted, rejected, escalations, drift, enforcement };
+    return { ok: true, decision: "inline", cadence, measured, admitted, rejected, escalations, drift, scored, enforcement };
   } catch (err) {
     // Fail-open but LOUD: the daemon keeps running, the failure is on the record.
     say("error", `[goal-steward] guard threw: ${err && err.message ? err.message : err}`);
@@ -1255,6 +1487,29 @@ function loadConfigRegistry() {
  * availability. The hardcoded CADENCE_REGISTRY wins; the config-driven archetype
  * cadences (config/.cadence-registry.json) fill in the rest.
  */
+/**
+ * Cadences already announced as unmetered. The warning is worth saying ONCE per
+ * cadence per process — `getCadenceDef` is called on every tick, and a line per
+ * tick is how a real signal becomes log noise nobody reads.
+ */
+const _unmeteredWarned = new Set();
+
+/**
+ * A plan-derived cadence arriving with no budget is the LAST hop of the mandate
+ * body joint, and it used to be its quietest: `budgetCents` was simply not set,
+ * the sub-session spawned with no spend cap, and nothing anywhere said so. The
+ * cap genuinely cannot be invented here — but its absence is now stated.
+ */
+function _warnUnmetered(name, obligationKey) {
+  if (_unmeteredWarned.has(name)) return;
+  _unmeteredWarned.add(name);
+  console.warn(
+    `[cadence] "${name}"${obligationKey ? ` (${obligationKey})` : ""} carries no budgetCents — ` +
+    "hq published no funding for the objective behind it, so this cadence spawns with NO spend cap. " +
+    "Fund the seat (Employee.payBasis.meteredBudget) or accept it as unmetered."
+  );
+}
+
 export function getCadenceDef(name) {
   if (CADENCE_REGISTRY[name]) return CADENCE_REGISTRY[name];
   const cfg = loadConfigRegistry()[name];
@@ -1268,6 +1523,7 @@ export function getCadenceDef(name) {
     if (Array.isArray(cfg.allowedTools) && cfg.allowedTools.length) def.allowedTools = cfg.allowedTools;
     if (cfg.guardModule) def.guardModule = cfg.guardModule;
     if (Number.isFinite(cfg.budgetCents)) def.budgetCents = cfg.budgetCents;
+    else _warnUnmetered(name, cfg.obligationKey);
     if (cfg.obligationKey) def.obligationKey = cfg.obligationKey;
     return def;
   }

package/scripts/daemon/cadence-handlers.test.mjs

@@ -615,3 +615,104 @@ test("brand-steward is registered guarded and cannot reach the admin foundation
   }
   assert.ok(def.allowedTools.includes("design_propose_change"), "proposing IS the lane");
 });
+
+// ---------------------------------------------------------------------------
+// messaging-inbound is WIDE (JOINT 3) — the LIVE default, not an injected stub
+// ---------------------------------------------------------------------------
+
+/**
+ * The regression this pins: `guardMessagingInbound` used to default to
+ * `lib/org/messaging.pullInbound`, whose events URL hardcodes
+ * `family=messaging,calling`. Board, calendar, escalation, approval, decision,
+ * files and handoff events were read off the wire and discarded, so a task
+ * assigned to this agent reached NOBODY — hq stands down for a live daemon
+ * (4d762d30) and the daemon was structurally deaf to the family.
+ *
+ * No `pullImpl` here ON PURPOSE: the point is which reader the REAL default
+ * resolves to. Only the network is faked.
+ */
+test("messaging-inbound (JOINT 3): the DEFAULT reader is wide — no family filter, and a board assignment arrives", async () => {
+  const root = tmpRoot();
+  const urls = [];
+  const written = [];
+  const ME = "member-me";
+
+  const json = (body) => ({
+    ok: true,
+    status: 200,
+    headers: { get: () => "application/json" },
+    text: async () => JSON.stringify(body),
+    json: async () => body,
+  });
+
+  const fetchImpl = async (url, init) => {
+    const u = String(url);
+    urls.push(`${(init && init.method) || "GET"} ${u}`);
+    if (u.includes("/events?")) {
+      return json({
+        events: [
+          {
+            seq: 501, family: "board", kind: "item.assigned", entity_id: "task-9",
+            actor: "member-boss", at: "2026-08-11T09:00:00Z",
+            // REDACTED BY DESIGN: no mention list, no recipient list.
+            payload: { actor: "member-boss", assignee: ME, assignedBy: "member-boss" },
+          },
+        ],
+        nextCursor: 501,
+      });
+    }
+    if (u.includes("board.context")) {
+      return json({ ok: true, result: { tasks: [{ id: "task-9", title: "Ship the transport joint", assigneeId: ME, col: "todo" }] } });
+    }
+    if (u.includes("messaging.channels")) return json({ ok: true, result: { channels: [] } });
+    return json({ ok: true, result: {} });
+  };
+
+  const res = await guardMessagingInbound(
+    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
+    {
+      cfg: { org: { cohort: { enabled: true, base: "https://x.test", token: "t" } } },
+      agentId: ME,
+      fetchImpl,
+      toInboxImpl: (e) => ({ id: e.id, service: "cohort", kind: e.kind, content: e.text }),
+      writeImpl: (service, item) => written.push({ service, item }),
+    },
+  );
+
+  const eventsUrl = urls.find((u) => u.includes("/events?"));
+  assert.ok(eventsUrl, "the ledger was read");
+  assert.ok(
+    !/family=/.test(eventsUrl),
+    `the events read must NOT pin a family — got ${eventsUrl}`,
+  );
+  assert.equal(res.wide, true, "the wide reader is the default, not an opt-in");
+  assert.equal(res.routed, 1, "a board assignment reaches the inbox pipeline");
+  assert.equal(written[0].item.kind, "task_assigned", "and carries the routing hint the classifier needs");
+  assert.equal(res.stats.bySurface.task_assigned, 1);
+});
+
+test("messaging-inbound (JOINT 3): MESSAGING_INBOUND_WIDE=0 falls back to the narrow reader — and SAYS SO", async () => {
+  const prev = process.env.MESSAGING_INBOUND_WIDE;
+  process.env.MESSAGING_INBOUND_WIDE = "0";
+  const logs = [];
+  try {
+    const res = await guardMessagingInbound(
+      { event: { cadence: "messaging-inbound" }, agentRoot: tmpRoot(), log: (lvl, m) => logs.push(`${lvl}:${m}`) },
+      {
+        cfg: { org: { cohort: { enabled: true, base: "https://x.test", token: "t" } } },
+        agentId: "member-me",
+        // The narrow reader pins family=messaging,calling on its URL; assert the
+        // degradation is announced rather than inferred from an empty inbox.
+        fetchImpl: async () => ({ ok: true, status: 200, headers: { get: () => "application/json" }, text: async () => JSON.stringify({ events: [], nextCursor: 0 }), json: async () => ({ events: [], nextCursor: 0 }) }),
+      },
+    );
+    assert.equal(res.wide, false);
+    assert.ok(
+      logs.some((l) => l.startsWith("warn:") && /WILL NOT arrive/.test(l)),
+      `a silent narrowing is the bug; got ${JSON.stringify(logs)}`,
+    );
+  } finally {
+    if (prev === undefined) delete process.env.MESSAGING_INBOUND_WIDE;
+    else process.env.MESSAGING_INBOUND_WIDE = prev;
+  }
+});