@cohortapp/agent-sdk 2.4.0 → 2.5.0

package/lib/kpi-sensors.mjs

@@ -0,0 +1,666 @@
+/**
+ * lib/kpi-sensors.mjs — the SENSOR REGISTRY: capability id → a real measurement.
+ *
+ * `lib/kpi.measureKpi` has always looked a sensor up in `deps.sensors[capability]`
+ * and, finding nothing, returned `{ok:false, reason:"no-implementation"}`. No
+ * registry existed anywhere in the repo, so EVERY objective measured to nothing,
+ * every gap was `null`, and `goals/admission.admit`'s honesty gate (the latest
+ * sample's `source` must be `method` or `human`) was unsatisfiable by
+ * construction. The reconciliation loop could not produce a single backlog item,
+ * ever. This file is the missing half.
+ *
+ * Three laws:
+ *
+ *   1. **A sensor READS. It never writes.** The measuring instrument may not
+ *      change the thing it measures. Any capability whose curated tool is not
+ *      `access:"read"` is refused BY NAME (`capability-is-not-a-read`) instead of
+ *      quietly missing — the derivation in lib/mandate/derive.mjs can and does
+ *      propose `task_update` and `escalation_raise` as fallback "sensors".
+ *   2. **Every number comes back with its evidence.** `{value, rowCount, detail}`
+ *      where `detail` names the method, the params actually sent and the rows the
+ *      reduction walked. `measureKpi` stamps `source:"method"` only because a
+ *      real capability really executed; that is what the honesty gate trusts.
+ *   3. **A sensor that cannot measure says so.** It returns `{ok:false, reason}`
+ *      — never a zero, never a throw. A read that fails, a read that comes back
+ *      empty when emptiness is not a measurement, a reduction that finds no
+ *      number: all three are `ok:false` with a distinct reason, all three are
+ *      logged, and none of them can become a sample. (An honest zero — "there
+ *      are no open escalations" — is a different thing and is returned as 0 with
+ *      `rowCount:0` and a `detail` saying so.)
+ *
+ * Injectable everywhere: `executeImpl`, the clock, the logger and the member-id
+ * resolver all arrive on `o`, so tests never touch the network.
+ *
+ * @module lib/kpi-sensors
+ */
+
+"use strict";
+
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { resolveAgentRoot } from "./agent-root.mjs";
+import { MANIFEST_REL } from "./capability/inventory.mjs";
+import { orgToolDef } from "./org/tool-surface.mjs";
+import { SENSOR_HINTS } from "./mandate/derive.mjs";
+
+const MS_HOUR = 3_600_000;
+const MS_DAY = 86_400_000;
+
+// ---------------------------------------------------------------------------
+// Return shapes
+// ---------------------------------------------------------------------------
+
+/** A measured number, with the rows it came from. */
+function measured(value, rowCount, detail) {
+  return { value, rowCount: Number.isFinite(rowCount) ? rowCount : null, detail: detail || null };
+}
+
+/** "I could not measure this." Never a zero, never a throw. */
+function unmeasurable(reason, detail) {
+  return { ok: false, reason, detail: detail || null };
+}
+
+// ---------------------------------------------------------------------------
+// Small pure helpers (exported: the tests drive them directly)
+// ---------------------------------------------------------------------------
+
+/** Dot-path read with numeric index support. Returns undefined, never throws. */
+export function pluck(obj, path) {
+  if (!path) return obj;
+  let cur = obj;
+  for (const seg of String(path).split(".")) {
+    if (cur == null) return undefined;
+    cur = cur[seg];
+  }
+  return cur;
+}
+
+/** First array-valued property of a result object (`{items:[…]}`, `{deals:[…]}`, …). */
+export function firstArray(result) {
+  if (Array.isArray(result)) return { key: "$", rows: result };
+  if (!result || typeof result !== "object") return null;
+  for (const [k, v] of Object.entries(result)) if (Array.isArray(v)) return { key: k, rows: v };
+  return null;
+}
+
+/** Mean of a numeric array, or null when empty. */
+export function mean(xs) {
+  const ns = (xs || []).filter((n) => Number.isFinite(n));
+  if (ns.length === 0) return null;
+  return ns.reduce((a, b) => a + b, 0) / ns.length;
+}
+
+/** Round to 4dp so a KPI series is comparable across runs. */
+function r4(n) {
+  return Number.isFinite(n) ? +n.toFixed(4) : n;
+}
+
+function ts(v) {
+  const t = Date.parse(v || "");
+  return Number.isFinite(t) ? t : null;
+}
+
+/**
+ * Generic numeric reduction over an arbitrary read payload — the escape hatch
+ * that lets a new KPI be added with a `sensor.params` change and no code edit.
+ *
+ * params: { field?, arrayPath?, where?:{key,equals}, sum?, avg?, count?, scale? }
+ * @returns {{value:number, rowCount:number|null, detail:object}|{ok:false, reason:string}}
+ */
+export function reduceGeneric(result, params = {}) {
+  const scale = Number.isFinite(Number(params.scale)) ? Number(params.scale) : 1;
+
+  if (params.field) {
+    const v = Number(pluck(result, params.field));
+    if (!Number.isFinite(v)) {
+      return unmeasurable("field-not-numeric", { field: params.field, saw: typeof pluck(result, params.field) });
+    }
+    return measured(r4(v * scale), null, { field: params.field, scale });
+  }
+
+  const picked = params.arrayPath ? pluck(result, params.arrayPath) : null;
+  const found = Array.isArray(picked) ? { key: params.arrayPath, rows: picked } : firstArray(result);
+  if (!found) {
+    return unmeasurable("no-array-to-reduce", { keys: result && typeof result === "object" ? Object.keys(result) : [] });
+  }
+
+  let rows = found.rows;
+  if (params.where && params.where.key) {
+    rows = rows.filter((row) => String(pluck(row, params.where.key)) === String(params.where.equals));
+  }
+
+  if (params.sum) {
+    const ns = rows.map((row) => Number(pluck(row, params.sum))).filter((n) => Number.isFinite(n));
+    if (ns.length === 0) {
+      return unmeasurable("no-numeric-rows", { arrayPath: found.key, sum: params.sum, rows: rows.length });
+    }
+    return measured(r4(ns.reduce((a, b) => a + b, 0) * scale), rows.length, { arrayPath: found.key, sum: params.sum, scale });
+  }
+  if (params.avg) {
+    const m = mean(rows.map((row) => Number(pluck(row, params.avg))));
+    if (m == null) {
+      return unmeasurable("no-numeric-rows", { arrayPath: found.key, avg: params.avg, rows: rows.length });
+    }
+    return measured(r4(m * scale), rows.length, { arrayPath: found.key, avg: params.avg, scale });
+  }
+  return measured(rows.length * scale, rows.length, { arrayPath: found.key, mode: "count", scale });
+}
+
+// ---------------------------------------------------------------------------
+// The specs — one per genuinely measurable capability
+// ---------------------------------------------------------------------------
+
+/**
+ * `input(params, ctx)`  → the tool input actually sent (evidence records this).
+ * `reduce(result, ctx)` → `measured()` or `unmeasurable()`.
+ * `needsMemberId`       → resolve this seat's member id before reducing.
+ *
+ * @type {Record<string, {metrics:string[], defaultMetric:string, unit:string, direction:string, input?:Function, reduce:Function, needsMemberId?:boolean}>}
+ */
+export const SENSOR_SPECS = Object.freeze({
+  // ── board / commitments ────────────────────────────────────────────────
+  board_ready: {
+    metrics: ["on_time_rate", "open_count", "overdue_count"],
+    defaultMetric: "on_time_rate",
+    unit: "%",
+    direction: "up",
+    input: () => ({}),
+    reduce(result, ctx) {
+      const all = (result && result.items) || [];
+      if (all.length === 0) return unmeasurable("no-rows", { read: "board.ready", items: 0 });
+      const scope = String(ctx.params.scope || "all");
+      const items = scope === "mine" && ctx.memberId ? all.filter((i) => i.assigneeId === ctx.memberId) : all;
+      if (scope === "mine" && !ctx.memberId) {
+        return unmeasurable("member-id-unresolved", { scope, read: "board.ready" });
+      }
+      if (items.length === 0) return unmeasurable("no-rows-in-scope", { scope, of: all.length });
+      const overdue = items.filter((i) => {
+        const due = ts(i.dueAt);
+        return due != null && due < ctx.nowMs;
+      });
+      const metric = String(ctx.params.metric || this.defaultMetric);
+      const detail = { read: "board.ready", scope, considered: items.length, overdue: overdue.length, withDueDate: items.filter((i) => ts(i.dueAt) != null).length };
+      if (metric === "open_count") return measured(items.length, items.length, detail);
+      if (metric === "overdue_count") return measured(overdue.length, items.length, detail);
+      // An item with no due date cannot be late — it counts as on time, and the
+      // `withDueDate` evidence field is what tells an operator how much of the
+      // rate is actually load-bearing.
+      return measured(r4(((items.length - overdue.length) / items.length) * 100), items.length, detail);
+    },
+  },
+
+  // ── governance / decision latency ──────────────────────────────────────
+  decision_list: {
+    metrics: ["open_age_days", "decided_latency_days", "open_count"],
+    defaultMetric: "open_age_days",
+    unit: "days",
+    direction: "down",
+    input: (params) => (params && params.status ? { status: params.status } : {}),
+    reduce(result, ctx) {
+      const all = (result && result.decisions) || [];
+      if (all.length === 0) return unmeasurable("no-rows", { read: "decision.list", decisions: 0 });
+      const open = all.filter((d) => d.status === "proposed" || (!d.decidedAt && d.status !== "superseded"));
+      const decided = all.filter((d) => ts(d.decidedAt) != null && ts(d.createdAt) != null);
+      const metric = String(ctx.params.metric || this.defaultMetric);
+      const detail = { read: "decision.list", total: all.length, open: open.length, decided: decided.length };
+
+      if (metric === "open_count") return measured(open.length, all.length, detail);
+      if (metric === "decided_latency_days") {
+        const m = mean(decided.map((d) => (ts(d.decidedAt) - ts(d.createdAt)) / MS_DAY));
+        if (m == null) return unmeasurable("no-decided-decisions", detail);
+        return measured(r4(m), decided.length, detail);
+      }
+      // open_age_days: the backlog that is costing the org time RIGHT NOW. Zero
+      // undecided decisions is a real measurement of zero (the read succeeded and
+      // returned rows) — not an absence.
+      if (open.length === 0) return measured(0, all.length, { ...detail, note: "no undecided decisions — an honest zero, not a missing sample" });
+      const m = mean(open.map((d) => (ctx.nowMs - (ts(d.createdAt) ?? ctx.nowMs)) / MS_DAY));
+      return measured(r4(m), open.length, detail);
+    },
+  },
+
+  // ── email responsiveness ───────────────────────────────────────────────
+  email_inbox: {
+    metrics: ["first_reply_hours", "unread_backlog_count", "oldest_unread_hours"],
+    defaultMetric: "first_reply_hours",
+    unit: "hours",
+    direction: "down",
+    input: (params) => {
+      const i = {};
+      if (params && params.limit) i.limit = Number(params.limit);
+      if (params && params.mailboxId) i.mailboxId = String(params.mailboxId);
+      return i;
+    },
+    reduce(result, ctx) {
+      const msgs = (result && result.messages) || [];
+      if (msgs.length === 0) return unmeasurable("no-rows", { read: "email.inbox", messages: 0 });
+      const inbound = msgs.filter((m) => String(m.direction).toUpperCase() === "INBOUND");
+      const outbound = msgs.filter((m) => String(m.direction).toUpperCase() === "OUTBOUND");
+      const metric = String(ctx.params.metric || this.defaultMetric);
+      const detail = { read: "email.inbox", messages: msgs.length, inbound: inbound.length, outbound: outbound.length };
+
+      if (metric === "unread_backlog_count") {
+        return measured(inbound.filter((m) => !m.readAt).length, inbound.length, detail);
+      }
+      if (metric === "oldest_unread_hours") {
+        const ages = inbound.filter((m) => !m.readAt).map((m) => (ctx.nowMs - (ts(m.receivedAt) ?? ctx.nowMs)) / MS_HOUR);
+        if (ages.length === 0) return measured(0, inbound.length, { ...detail, note: "nothing unread" });
+        return measured(r4(Math.max(...ages)), ages.length, detail);
+      }
+
+      // first_reply_hours: per inbound message, the first outbound in the SAME
+      // thread that left after it. Unanswered inbound is reported in the evidence
+      // rather than folded into the mean — an unanswered mail has no latency yet,
+      // and averaging it in as zero would make silence look like speed.
+      if (inbound.length === 0) return unmeasurable("no-inbound-mail", detail);
+      const latencies = [];
+      let unanswered = 0;
+      for (const m of inbound) {
+        const at = ts(m.receivedAt) ?? ts(m.createdAt);
+        if (at == null) continue;
+        const replies = outbound
+          .filter((o) => o.threadId === m.threadId)
+          .map((o) => ts(o.sentAt) ?? ts(o.createdAt))
+          .filter((t) => t != null && t > at);
+        if (replies.length === 0) { unanswered += 1; continue; }
+        latencies.push((Math.min(...replies) - at) / MS_HOUR);
+      }
+      const m = mean(latencies);
+      if (m == null) return unmeasurable("no-answered-inbound", { ...detail, unanswered });
+      return measured(r4(m), latencies.length, { ...detail, answered: latencies.length, unanswered });
+    },
+  },
+
+  // ── messaging ──────────────────────────────────────────────────────────
+  messaging_channels: {
+    metrics: ["active_channel_count"],
+    defaultMetric: "active_channel_count",
+    unit: "count",
+    direction: "up",
+    input: () => ({}),
+    reduce(result) {
+      const chs = (result && result.channels) || [];
+      if (chs.length === 0) return unmeasurable("no-rows", { method: "channel.list", channels: 0 });
+      const active = chs.filter((c) => !c.archived);
+      return measured(active.length, chs.length, { method: "channel.list", total: chs.length, archived: chs.length - active.length });
+    },
+  },
+
+  messaging_history: {
+    metrics: ["mention_response_rate", "participation_rate", "message_count"],
+    defaultMetric: "mention_response_rate",
+    unit: "%",
+    direction: "up",
+    needsMemberId: true,
+    input: (params) => {
+      const i = { channelId: String((params && params.channelId) || "") };
+      if (params && params.limit) i.limit = Number(params.limit);
+      return i;
+    },
+    reduce(result, ctx) {
+      if (!ctx.params.channelId) return unmeasurable("missing-param", { required: "channelId" });
+      const msgs = (result && result.messages) || [];
+      if (msgs.length === 0) return unmeasurable("no-rows", { method: "messaging.history", channelId: ctx.params.channelId });
+      const metric = String(ctx.params.metric || this.defaultMetric);
+      const mine = msgs.filter((m) => m.authorId === ctx.memberId);
+      const detail = { method: "messaging.history", channelId: ctx.params.channelId, messages: msgs.length, mine: mine.length };
+
+      if (metric === "message_count") return measured(msgs.length, msgs.length, detail);
+      if (!ctx.memberId) return unmeasurable("member-id-unresolved", detail);
+      if (metric === "participation_rate") {
+        return measured(r4((mine.length / msgs.length) * 100), msgs.length, detail);
+      }
+      // mention_response_rate: of the messages that @-mentioned me, how many were
+      // followed by a message of mine within `windowHours`.
+      const windowHours = Number.isFinite(Number(ctx.params.windowHours)) ? Number(ctx.params.windowHours) : 24;
+      const mentions = msgs.filter((m) => Array.isArray(m.mentions) && m.mentions.includes(ctx.memberId));
+      if (mentions.length === 0) return unmeasurable("no-mentions-in-window", { ...detail, windowHours });
+      const mineAt = mine.map((m) => ts(m.createdAt)).filter((t) => t != null);
+      let answered = 0;
+      for (const m of mentions) {
+        const at = ts(m.createdAt);
+        if (at == null) continue;
+        if (mineAt.some((t) => t > at && t - at <= windowHours * MS_HOUR)) answered += 1;
+      }
+      return measured(r4((answered / mentions.length) * 100), mentions.length, { ...detail, mentions: mentions.length, answered, windowHours });
+    },
+  },
+
+  // ── calendar ───────────────────────────────────────────────────────────
+  calendar_list: {
+    metrics: ["agenda_coverage", "upcoming_count"],
+    defaultMetric: "agenda_coverage",
+    unit: "%",
+    direction: "up",
+    input: (params) => {
+      const i = {};
+      for (const k of ["fromIso", "toIso", "calendarMemberId", "limit"]) {
+        if (params && params[k] != null) i[k] = params[k];
+      }
+      return i;
+    },
+    reduce(result, ctx) {
+      const events = (result && (result.events || result.meetings)) || [];
+      if (events.length === 0) return unmeasurable("no-rows", { method: "calendar.list", events: 0 });
+      const metric = String(ctx.params.metric || this.defaultMetric);
+      if (metric === "upcoming_count") {
+        return measured(events.length, events.length, { method: "calendar.list" });
+      }
+      const withAgenda = events.filter((e) => {
+        const a = e.agenda || e.description || e.notes || e.summary;
+        return typeof a === "string" && a.trim().length > 0;
+      });
+      return measured(r4((withAgenda.length / events.length) * 100), events.length, {
+        method: "calendar.list", events: events.length, withAgenda: withAgenda.length,
+      });
+    },
+  },
+
+  // ── pipeline / risk ────────────────────────────────────────────────────
+  crm_list_deals: {
+    metrics: ["open_pipeline_usd", "open_deal_count"],
+    defaultMetric: "open_pipeline_usd",
+    unit: "usd",
+    direction: "up",
+    input: (params) => {
+      // NOT a passthrough of `params`: hq's stage filter is a strict enum
+      // (INBOUND|QUALIFIED|PROPOSAL|NEGOTIATION|CLOSED) and rejects anything
+      // else with BAD_REQUEST. Open-ness is computed here from the stage field.
+      const i = {};
+      if (params && params.stage && /^(INBOUND|QUALIFIED|PROPOSAL|NEGOTIATION|CLOSED)$/.test(String(params.stage))) {
+        i.stage = String(params.stage);
+      }
+      return i;
+    },
+    reduce(result, ctx) {
+      const deals = (result && result.deals) || [];
+      if (deals.length === 0) return unmeasurable("no-rows", { method: "crm.listDeals", deals: 0 });
+      const open = deals.filter((d) => String(d.stage).toUpperCase() !== "CLOSED");
+      const metric = String(ctx.params.metric || this.defaultMetric);
+      const detail = { method: "crm.listDeals", total: deals.length, open: open.length };
+      if (metric === "open_deal_count") return measured(open.length, deals.length, detail);
+      const cents = open.map((d) => Number(d.valueCents)).filter((n) => Number.isFinite(n));
+      if (cents.length === 0) return unmeasurable("no-deal-values", detail);
+      return measured(r4(cents.reduce((a, b) => a + b, 0) / 100), open.length, { ...detail, valued: cents.length });
+    },
+  },
+
+  crm_list_escalations: {
+    metrics: ["open_count"],
+    defaultMetric: "open_count",
+    unit: "count",
+    direction: "down",
+    input: () => ({}),
+    reduce(result) {
+      const rows = (result && result.escalations) || [];
+      // Zero escalations is the GOOD value of a direction:"down" count, and the
+      // read genuinely answered. This is the one place an empty list is a real
+      // measurement rather than an absence — said out loud in the evidence.
+      return measured(rows.length, rows.length, {
+        method: "crm.listEscalations",
+        note: rows.length === 0 ? "no open escalations — a measured zero" : null,
+      });
+    },
+  },
+
+  // ── generic counts ─────────────────────────────────────────────────────
+  directory_list_captures: {
+    metrics: ["pending_count"], defaultMetric: "pending_count", unit: "count", direction: "down",
+    input: (params) => (params && params.status ? { status: params.status } : {}),
+    reduce: (result) => countOf(result, "directory.listCaptures"),
+  },
+  design_list_templates: {
+    metrics: ["template_count"], defaultMetric: "template_count", unit: "count", direction: "up",
+    input: () => ({}),
+    reduce: (result) => countOf(result, "branding.listTemplates"),
+  },
+  files_list: {
+    metrics: ["file_count"], defaultMetric: "file_count", unit: "count", direction: "up",
+    input: (params) => (params && params.folderId ? { folderId: params.folderId } : {}),
+    reduce: (result) => countOf(result, "files.list"),
+  },
+  knowledge_search: {
+    metrics: ["hit_count"], defaultMetric: "hit_count", unit: "count", direction: "up",
+    input: (params) => ({ query: String((params && params.query) || "") }),
+    reduce(result, ctx) {
+      if (!ctx.params.query) return unmeasurable("missing-param", { required: "query" });
+      return countOf(result, "knowledge.search");
+    },
+  },
+
+  // ── generic numeric escape hatches ─────────────────────────────────────
+  books_reports: {
+    metrics: ["generic"], defaultMetric: "generic", unit: null, direction: "up",
+    input: (params) => {
+      const i = { report: String((params && params.report) || "") };
+      if (params && params.from) i.from = params.from;
+      if (params && params.to) i.to = params.to;
+      return i;
+    },
+    reduce(result, ctx) {
+      if (!ctx.params.report) {
+        return unmeasurable("missing-param", { required: "report", accepts: "pl|balance|cashflow|agedAr|agedAp" });
+      }
+      return reduceGeneric(result, ctx.params);
+    },
+  },
+  org_read: {
+    metrics: ["generic"], defaultMetric: "generic", unit: null, direction: "up",
+    input: (params) => {
+      const i = { path: String((params && params.path) || "") };
+      if (params && params.query) i.query = params.query;
+      return i;
+    },
+    reduce(result, ctx) {
+      if (!ctx.params.path) return unmeasurable("missing-param", { required: "path" });
+      return reduceGeneric(result, ctx.params);
+    },
+  },
+});
+
+function countOf(result, method) {
+  const found = firstArray(result);
+  if (!found) return unmeasurable("no-array-to-reduce", { method, keys: result && typeof result === "object" ? Object.keys(result) : [] });
+  return measured(found.rows.length, found.rows.length, { method, arrayKey: found.key });
+}
+
+// ---------------------------------------------------------------------------
+// Refusals — every capability the derivation can pick gets a NAMED answer
+// ---------------------------------------------------------------------------
+
+/** Capabilities lib/mandate/derive.SENSOR_HINTS can bind a metric to. */
+export function hintedCapabilities() {
+  const out = new Set();
+  for (const h of SENSOR_HINTS) for (const c of h.caps) out.add(c);
+  return out;
+}
+
+/** Why this capability is not a sensor. Returns null when it IS one. */
+export function refusalFor(capability) {
+  if (SENSOR_SPECS[capability]) return null;
+  const def = orgToolDef(capability);
+  if (!def) return "not a curated org tool — nothing in this SDK can execute it as a measurement";
+  if (capability === "approval_wait") {
+    return "approval_wait is a long-poll, not an aggregate read — measuring with it would block the daemon for up to 55s per objective";
+  }
+  if (def.access !== "read") {
+    return `"${capability}" is a ${def.access} capability — a sensor may not mutate the org to measure it`;
+  }
+  return `"${capability}" is a read, but this registry has no reduction that turns its payload into a number`;
+}
+
+// ---------------------------------------------------------------------------
+// Reachability
+// ---------------------------------------------------------------------------
+
+/**
+ * The reachable capability ids from `config/capability-manifest.json`.
+ *
+ * Returns **undefined** — not an empty Set — when the manifest is missing or
+ * unreadable, and logs. `measureKpi` only enforces reachability when
+ * `deps.reachable !== undefined`, so an empty Set here would silently refuse
+ * every measurement in the fleet the first time a manifest failed to parse.
+ *
+ * @param {string} agentRoot @param {object} [deps] { log }
+ * @returns {Set<string>|undefined}
+ */
+export function reachableCapabilities(agentRoot, deps = {}) {
+  const log = typeof deps.log === "function" ? deps.log : () => {};
+  const p = join(resolveAgentRoot(agentRoot), MANIFEST_REL);
+  if (!existsSync(p)) {
+    log("warn", `[kpi-sensors] no capability manifest at ${p} — measuring WITHOUT the reachability check (run \`cohort inventory\`)`);
+    return undefined;
+  }
+  try {
+    const m = JSON.parse(readFileSync(p, "utf-8"));
+    const entries = Array.isArray(m.entries) ? m.entries : [];
+    const out = new Set();
+    for (const e of entries) {
+      if (!e || !e.reachable) continue;
+      out.add(String(e.id));
+      // org-plane ids are the bare tool name already; tolerate a "plane:" prefix.
+      const bare = String(e.id).replace(/^[a-z]+:/, "");
+      if (bare) out.add(bare);
+    }
+    if (out.size === 0) {
+      log("warn", `[kpi-sensors] capability manifest has ZERO reachable entries — measuring without the reachability check rather than refusing every objective`);
+      return undefined;
+    }
+    return out;
+  } catch (err) {
+    log("warn", `[kpi-sensors] capability manifest unreadable (${err && err.message ? err.message : err}) — measuring without the reachability check`);
+    return undefined;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// The registry
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the `deps.sensors` registry `lib/kpi.measureKpi` looks a capability up in.
+ *
+ * Every capability the mandate derivation can bind a metric to is present:
+ * measurable ones as a real org read, the rest as a refusal that names WHY.
+ * `measureKpi` turns a refusal into `{ok:false, reason}` — never a sample.
+ *
+ * @param {object} o - {
+ *   agentRoot, executeImpl?, now?, log?, memberId?, resolveMemberIdImpl?, fetchImpl?
+ * }
+ * @returns {Record<string, (a:{params:object, objective:object}) => Promise<object>>}
+ */
+export function buildSensorRegistry(o = {}) {
+  const agentRoot = resolveAgentRoot(o.agentRoot);
+  const log = typeof o.log === "function" ? o.log : () => {};
+  const now = typeof o.now === "function" ? o.now : Date.now;
+  let execute = o.executeImpl || null;
+
+  const exec = async (name, input) => {
+    if (!execute) execute = (await import("./org/tool-surface.mjs")).executeOrgTool;
+    return execute(name, input, { agentRoot, fetchImpl: o.fetchImpl });
+  };
+
+  // Member id: env first (the daemon already has it), then a memoized directory
+  // lookup by slug. Never fatal — a sensor that needs it says `member-id-unresolved`.
+  let memberIdCache = o.memberId || null;
+  let memberIdTried = !!o.memberId;
+  const resolveMemberId = async () => {
+    if (memberIdTried) return memberIdCache;
+    memberIdTried = true;
+    if (typeof o.resolveMemberIdImpl === "function") {
+      try { memberIdCache = (await o.resolveMemberIdImpl()) || null; } catch { memberIdCache = null; }
+      return memberIdCache;
+    }
+    const env = o.env || process.env;
+    if (env.COHORT_AGENT_ID) { memberIdCache = String(env.COHORT_AGENT_ID); return memberIdCache; }
+    const slug = env.COHORT_MEMBER_SLUG || "";
+    if (!slug) {
+      log("info", "[kpi-sensors] no COHORT_AGENT_ID and no COHORT_MEMBER_SLUG — sensors scoped to 'me' will report member-id-unresolved");
+      return null;
+    }
+    try {
+      const r = await exec("org_directory", {});
+      const rows = (r && r.ok && ((r.result && r.result.members) || r.result)) || [];
+      const hit = Array.isArray(rows) ? rows.find((m) => m && m.slug === slug) : null;
+      memberIdCache = (hit && hit.id) || null;
+      if (!memberIdCache) log("warn", `[kpi-sensors] member slug "${slug}" not found in the org directory — 'me'-scoped sensors cannot measure`);
+    } catch (err) {
+      log("warn", `[kpi-sensors] directory lookup for "${slug}" failed: ${err && err.message ? err.message : err}`);
+    }
+    return memberIdCache;
+  };
+
+  const registry = {};
+
+  for (const [capability, spec] of Object.entries(SENSOR_SPECS)) {
+    registry[capability] = async ({ params = {}, objective } = {}) => {
+      const p = params && typeof params === "object" ? params : {};
+      const input = typeof spec.input === "function" ? spec.input(p, { objective }) : p;
+      let res;
+      try {
+        res = await exec(capability, input);
+      } catch (err) {
+        log("error", `[kpi-sensors] ${capability} threw: ${err && err.message ? err.message : err}`);
+        return unmeasurable("sensor-threw", { capability, message: String(err && err.message ? err.message : err) });
+      }
+      if (!res || res.ok !== true) {
+        const e = (res && res.error) || {};
+        log("warn", `[kpi-sensors] ${capability} read failed (${e.code || "?"}): ${e.message || "no error frame"}`);
+        return unmeasurable("read-failed", { capability, input, code: e.code || null, message: e.message || null });
+      }
+      const ctx = {
+        params: p,
+        nowMs: now(),
+        memberId: spec.needsMemberId || p.scope === "mine" ? await resolveMemberId() : (memberIdCache || null),
+        log,
+      };
+      let out;
+      try {
+        out = spec.reduce.call(spec, res.result, ctx);
+      } catch (err) {
+        log("error", `[kpi-sensors] ${capability} reduction threw: ${err && err.message ? err.message : err}`);
+        return unmeasurable("reduce-threw", { capability, message: String(err && err.message ? err.message : err) });
+      }
+      if (!out || out.ok === false) {
+        log("warn", `[kpi-sensors] ${capability} could not be reduced to a number: ${(out && out.reason) || "unknown"}`);
+        return out || unmeasurable("reduce-empty", { capability });
+      }
+      return {
+        value: out.value,
+        rowCount: out.rowCount,
+        detail: {
+          capability,
+          metric: String(p.metric || spec.defaultMetric),
+          unit: spec.unit,
+          input,
+          ...(out.detail || {}),
+        },
+      };
+    };
+  }
+
+  // Everything the derivation can bind but this registry will not measure.
+  for (const capability of hintedCapabilities()) {
+    if (registry[capability]) continue;
+    const why = refusalFor(capability);
+    registry[capability] = async () => {
+      log("warn", `[kpi-sensors] refusing to measure via "${capability}": ${why}`);
+      return unmeasurable("capability-is-not-a-sensor", { capability, why });
+    };
+  }
+
+  return registry;
+}
+
+export default {
+  SENSOR_SPECS,
+  buildSensorRegistry,
+  reachableCapabilities,
+  refusalFor,
+  hintedCapabilities,
+  reduceGeneric,
+  firstArray,
+  pluck,
+  mean,
+};