@cohortapp/agent-sdk 2.5.1 → 2.6.1

package/lib/org/engagement.mjs

@@ -0,0 +1,1056 @@
+/**
+ * lib/org/engagement.mjs — the judgement to bring the right people in, and the
+ * means to do it.
+ *
+ * ── THE PROBLEM THIS SOLVES ──
+ * An agent that never engages anyone dies quietly: it hits a blocker only a
+ * human can clear, records the fact in a journal nobody reads, and the requester
+ * hears nothing until they chase. That is the observed failure — the execution
+ * ladder's own journal shows nine `escalate` decisions, every one with
+ * `spoke: false`, because raising an OpenQuestion row is not the same as
+ * speaking to a person.
+ *
+ * An agent that engages everyone is worse. It is trivially easy to build: any
+ * "who might care about this?" heuristic will happily produce five names for
+ * every task, and within a week every human in the org filters it. A filtered
+ * channel cannot be unfiltered.
+ *
+ * So the whole difficulty is the THRESHOLD, and this module's job is to state it
+ * explicitly, apply it mechanically, and record the answer either way.
+ *
+ * ── THE THRESHOLD ──
+ *
+ *   Engage exactly when a SPECIFIC NAMED PERSON'S action or consent is a
+ *   PRECONDITION for the work to proceed or to be safe, and the agent cannot
+ *   supply it itself.
+ *
+ * Three words do the work:
+ *
+ *   PRECONDITION — not "useful input", not "they'd want to know". If the work
+ *     can move without them, it moves without them. This is the clause that
+ *     excludes the entire FYI class, which is where the flood comes from.
+ *   SPECIFIC NAMED — if the judgement cannot name who, it has not identified a
+ *     blocker, it has identified an anxiety. Broadcasting an anxiety to a
+ *     channel is how "engage the right people" becomes "engage everyone".
+ *   CANNOT SUPPLY ITSELF — an agent that asks a human for something it could
+ *     have looked up has outsourced its own job. `selfServeExhausted` is a
+ *     required input for the blocked trigger precisely so this cannot be
+ *     skipped by accident.
+ *
+ * Everything the threshold excludes has somewhere else to go. FYI belongs on the
+ * board (a comment, an attachment, a status change) — PULL, not push. That is
+ * the trade being made: the board absorbs "should know", messaging is reserved
+ * for "must act". If the board is doing its job, the engagement bar can stay
+ * this high without anybody being left in the dark.
+ *
+ * ── FOUR TRIGGERS, EACH A NECESSITY TEST ──
+ *
+ *   blocked_on_other       the work has stopped and the thing unblocking it is
+ *                          owned by someone else (a decision, an access grant,
+ *                          information only they hold). Requires
+ *                          `selfServeExhausted`.
+ *   irreversible_or_external  the next action leaves the org's boundary, spends
+ *                          money, or cannot be undone. Consent is required
+ *                          BEFORE, because "ask forgiveness" is not available
+ *                          for irreversible acts.
+ *   mandatory_review       a policy or role requires a second pair of eyes
+ *                          before the artefact lands.
+ *   commitment_at_risk     a promise made to a named person will be missed, or
+ *                          the run failed. They are about to act on stale
+ *                          information. This is the owner's actual complaint —
+ *                          silence after a failure — and it is a trigger, not a
+ *                          courtesy.
+ *
+ * ── AND AN EXPLICIT "NOBODY" ──
+ * Every non-engagement is an OUTCOME with a reason code, appended to the ledger:
+ * `self_contained`, `self_serve_available`, `fyi_only`, `already_engaged`,
+ * `rate_limited_*`, `unroutable`, `send_blocked`. Silence is never the default
+ * branch; it is a decision that has to be written down like any other. Engaging
+ * nobody when someone is blocked is the failure being fixed — so it must be
+ * possible to point at a row and say the agent considered it and declined.
+ *
+ * ── SHAPE ──
+ * `decideEngagement` is PURE: work + context in, decision out, no clock of its
+ * own, no disk, no network. `runEngagement` is the only effectful half, and it
+ * routes through `messaging.sendMessage`, which runs the shared send-gate — the
+ * gate is never bypassed, and a gate refusal is recorded as `send_blocked`
+ * rather than dropped.
+ *
+ * The message body is a TEMPLATE, deliberately. The holding-message path in the
+ * daemon spawns a `claude --print` child to write one courtesy sentence and
+ * loses that race two times in three; an engagement that only fires when an LLM
+ * spawn wins a 60s race is an engagement that does not fire. A template cannot
+ * time out.
+ *
+ * @module lib/org/engagement
+ */
+
+"use strict";
+
+import {
+  DEFAULT_LIMITS,
+  dedupeKeyFor,
+  loadEngagements,
+  appendEngagement,
+  checkGuardrails,
+} from "./engagement-ledger.mjs";
+
+// ---------------------------------------------------------------------------
+// Vocabulary
+// ---------------------------------------------------------------------------
+
+/** The four things that make another person a precondition. */
+export const TRIGGERS = Object.freeze([
+  "irreversible_or_external",
+  "blocked_on_other",
+  "mandatory_review",
+  "commitment_at_risk",
+]);
+
+/**
+ * Trigger priority, ordered by the COST OF NOT ENGAGING:
+ *   1. an unsafe act happens that cannot be taken back
+ *   2. the work stops dead
+ *   3. the artefact cannot land
+ *   4. someone acts on information they don't know is stale
+ * The primary trigger decides the framing and the surface; the others still ride
+ * along in `why`, so a decision never hides the fact that several things fired.
+ */
+const TRIGGER_RANK = Object.freeze({
+  irreversible_or_external: 0,
+  blocked_on_other: 1,
+  mandatory_review: 2,
+  commitment_at_risk: 3,
+});
+
+/**
+ * Blocker kinds that are, by definition, owned by someone else.
+ * `capacity` is NOT here: "I am busy" is the agent's own queue problem, and
+ * treating it as a blocker is how an agent starts asking humans to do its work.
+ * A capacity blocker only qualifies when it names an explicit `ownerId`.
+ */
+const OTHER_OWNED_BLOCKERS = Object.freeze(new Set(["decision", "access", "information", "approval"]));
+
+/** Surfaces, cheapest first. Cost = people newly exposed + persistence created. */
+export const SURFACES = Object.freeze(["reply_in_place", "dm", "existing_channel", "new_room"]);
+
+/** How many people one ask may name. Beyond this you have called a meeting. */
+const MAX_TARGETS = 3;
+
+// ---------------------------------------------------------------------------
+// Small helpers (pure)
+// ---------------------------------------------------------------------------
+
+const lc = (v) => (v == null ? "" : String(v).toLowerCase());
+
+/** Split a scope phrase into meaningful tokens (stopwords out, ≥3 chars). */
+const STOPWORDS = new Set([
+  "the", "and", "for", "with", "from", "that", "this", "into", "our", "are", "was",
+  "who", "what", "when", "how", "why", "can", "not", "but", "all", "any", "its",
+]);
+function tokens(text) {
+  return Array.from(
+    new Set(
+      lc(text)
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t)),
+    ),
+  );
+}
+
+function memberId(m) {
+  return String((m && (m.id || m.memberId || m.slug)) || "");
+}
+function memberName(m) {
+  return String((m && (m.displayName || m.name || m.slug || m.id)) || "");
+}
+
+/** Active, real, not me. A DM to an archived seat is a message to a void. */
+function engageable(m, me) {
+  if (!m) return false;
+  const id = memberId(m);
+  if (!id || id === String(me)) return false;
+  const status = lc(m.status);
+  if (status && status !== "active" && status !== "online" && status !== "busy") return false;
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// 1. WHETHER — which necessity test, if any, fires
+// ---------------------------------------------------------------------------
+
+/**
+ * Evaluate every trigger against a piece of work. PURE.
+ *
+ * Returns both what fired and — just as importantly — what nearly fired and
+ * why it didn't, so a "nobody" decision can explain itself in the ledger.
+ *
+ * @param {object} work see module docs / `decideEngagement`
+ * @returns {{fired:object[], suppressed:object[]}}
+ */
+export function evaluateTriggers(work = {}) {
+  const fired = [];
+  const suppressed = [];
+  const state = lc(work.state) || "in_progress";
+  const risk = work.risk || {};
+  const blocker = work.blocker || null;
+  const review = work.review || null;
+  const commitment = work.commitment || null;
+
+  // ── irreversible / external / financial ──
+  // Gated on the act being IMMINENT. Classifying finished work as needing
+  // consent is how an agent asks permission for something it already did.
+  if (risk.irreversible || risk.external || risk.financial) {
+    if (state === "done") {
+      suppressed.push({
+        trigger: "irreversible_or_external",
+        code: "act_already_taken",
+        detail: "the risky action is already complete — consent after the fact is theatre; this belongs in the record, not in someone's DMs",
+      });
+    } else {
+      const kinds = ["irreversible", "external", "financial"].filter((k) => risk[k]);
+      fired.push({
+        trigger: "irreversible_or_external",
+        code: `consent_required:${kinds.join("+")}`,
+        scope: work.scope || (blocker && blocker.scope) || work.title || "",
+        detail: `the next action is ${kinds.join(" and ")} and cannot be taken back`,
+      });
+    }
+  }
+
+  // ── blocked on another party ──
+  if (state === "blocked" || state === "failed") {
+    if (!blocker) {
+      suppressed.push({
+        trigger: "blocked_on_other",
+        code: "blocker_unnamed",
+        detail: "the work reports blocked but names no blocker — nobody can be asked for an unnamed thing",
+      });
+    } else {
+      const kind = lc(blocker.kind);
+      const otherOwned = OTHER_OWNED_BLOCKERS.has(kind) || !!blocker.ownerId;
+      if (!otherOwned) {
+        suppressed.push({
+          trigger: "blocked_on_other",
+          code: "blocker_is_mine",
+          detail: `blocker kind "${kind || "unknown"}" is the agent's own to clear — asking a human to clear it is outsourcing the work`,
+        });
+      } else if (work.selfServeExhausted !== true) {
+        // THE anti-outsourcing gate. Explicitly requires a positive assertion:
+        // an absent flag reads as "hasn't tried", which is the safe reading.
+        suppressed.push({
+          trigger: "blocked_on_other",
+          code: "self_serve_available",
+          detail: "the agent has not exhausted what it can do itself — engaging now would hand a human the agent's own next step",
+        });
+      } else {
+        fired.push({
+          trigger: "blocked_on_other",
+          code: `blocked:${kind || "unspecified"}`,
+          scope: blocker.scope || work.scope || work.title || "",
+          detail: blocker.detail || `blocked on a ${kind} only another party can give`,
+          ownerId: blocker.ownerId || null,
+        });
+      }
+    }
+  }
+
+  // ── mandatory review ──
+  if (review && review.required) {
+    fired.push({
+      trigger: "mandatory_review",
+      code: `review_required:${lc(review.kind) || "unspecified"}`,
+      scope: review.scope || work.scope || work.title || "",
+      detail: review.detail || "a second pair of eyes is required before this lands",
+      ownerId: review.reviewerId || null,
+    });
+  } else if (review && review.requested) {
+    // "It'd be nice to have someone look" is not a precondition.
+    suppressed.push({
+      trigger: "mandatory_review",
+      code: "review_optional",
+      detail: "review was wanted but is not required — the artefact can land without it",
+    });
+  }
+
+  // ── commitment at risk ──
+  if (commitment && commitment.toMemberId) {
+    if (commitment.atRisk || state === "failed") {
+      fired.push({
+        trigger: "commitment_at_risk",
+        code: state === "failed" ? "commitment_failed" : "commitment_slipping",
+        scope: work.scope || work.title || "",
+        detail:
+          state === "failed"
+            ? "the run failed and the person who asked is still waiting — silence here is the exact failure being fixed"
+            : "a promise made to a named person will be missed",
+        ownerId: commitment.toMemberId,
+      });
+    } else {
+      suppressed.push({
+        trigger: "commitment_at_risk",
+        code: "commitment_on_track",
+        detail: "the commitment is on track — a progress ping nobody asked for is noise",
+      });
+    }
+  }
+
+  fired.sort((a, b) => (TRIGGER_RANK[a.trigger] ?? 9) - (TRIGGER_RANK[b.trigger] ?? 9));
+  return { fired, suppressed };
+}
+
+// ---------------------------------------------------------------------------
+// 2. WHO — resolved from the directory, by a ladder, never by guesswork
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve who to engage. PURE over the injected directory.
+ *
+ * Four rungs, first hit wins, and the rung is recorded on every target so a
+ * reader can tell "the work named them" from "we matched two keywords against a
+ * job title". They are not the same claim and must not look the same.
+ *
+ *   explicit    — the work names them (blocker owner, named reviewer, the person
+ *                 owed the commitment, the requester). Highest confidence: this
+ *                 is not inference at all.
+ *   ownership   — the directory says they own the scope (`owns[]`, or an
+ *                 escalation path / team that names it exactly).
+ *   expertise   — role title / tagline / team overlaps the scope. Requires TWO
+ *                 distinct token matches, or one token of ≥5 characters. One
+ *                 short keyword ("api", "ops") matching a job title is a
+ *                 coincidence, and coincidence is not a reason to interrupt
+ *                 someone.
+ *   supervisory — my own supervisor. The escalation path of last resort, used
+ *                 only when nothing above matched: an unanswerable question is
+ *                 better sent up the line than sprayed sideways.
+ *
+ * Nothing at all ⇒ `unroutable`, which is an outcome, not a fallback to
+ * broadcast. Broadcasting to a channel because we could not name a person is
+ * exactly the behaviour the threshold exists to prevent.
+ *
+ * @param {object} o { work, trigger, directory, me, maxTargets? }
+ * @returns {{targets:object[], why:string[]}}
+ */
+export function resolveTargets(o = {}) {
+  const { work = {}, trigger = {}, directory = [], me = "" } = o;
+  const max = Number.isFinite(o.maxTargets) ? o.maxTargets : MAX_TARGETS;
+  const byId = new Map();
+  for (const m of Array.isArray(directory) ? directory : []) {
+    const id = memberId(m);
+    if (id) byId.set(id, m);
+  }
+  const why = [];
+  const picked = new Map();
+
+  const add = (id, rung, reason) => {
+    const key = String(id || "").trim();
+    if (!key || picked.has(key) || picked.size >= max) return false;
+    const m = byId.get(key) || null;
+    if (m && !engageable(m, me)) {
+      why.push(`skipped ${key}: not an engageable seat (status=${lc(m.status) || "unknown"})`);
+      return false;
+    }
+    if (!m && key === String(me)) return false;
+    picked.set(key, {
+      memberId: key,
+      name: m ? memberName(m) : key,
+      role: m ? String(m.roleTitle || m.title || "") : "",
+      team: m ? String(m.teamName || "") : "",
+      rung,
+      why: reason,
+    });
+    why.push(`${key} (${rung}): ${reason}`);
+    return true;
+  };
+
+  // ── rung 1: explicit ──
+  const explicit = [];
+  if (trigger.ownerId) explicit.push([trigger.ownerId, "the work names them as the party that must act"]);
+  if (work.blocker && work.blocker.ownerId) explicit.push([work.blocker.ownerId, "named as the owner of the blocker"]);
+  if (work.review && work.review.reviewerId) explicit.push([work.review.reviewerId, "named as the required reviewer"]);
+  if (work.approverId) explicit.push([work.approverId, "named as the approver for this class of action"]);
+  if (work.commitment && work.commitment.toMemberId && (work.commitment.atRisk || lc(work.state) === "failed")) {
+    explicit.push([work.commitment.toMemberId, "they are the person waiting on this and it is not going to arrive as promised"]);
+  }
+  // The requester is explicit ONLY for the trigger they are actually party to.
+  // Copying the requester onto an unrelated internal blocker is CC-culture.
+  if (
+    work.origin &&
+    work.origin.requesterId &&
+    (trigger.trigger === "commitment_at_risk" || lc(work.state) === "failed")
+  ) {
+    explicit.push([work.origin.requesterId, "they asked for this and are owed the outcome"]);
+  }
+  for (const [id, reason] of explicit) add(id, "explicit", reason);
+  if (picked.size) return { targets: [...picked.values()], why };
+
+  const scopeTokens = tokens(trigger.scope || work.scope || work.title || "");
+
+  // ── rung 2: ownership ──
+  if (scopeTokens.length) {
+    for (const m of byId.values()) {
+      if (!engageable(m, me)) continue;
+      const owns = Array.isArray(m.owns) ? m.owns.map(lc) : [];
+      const hitOwns = owns.find((ownScope) => scopeTokens.some((t) => ownScope.includes(t)));
+      if (hitOwns) {
+        add(memberId(m), "ownership", `the directory records them as owning "${hitOwns}"`);
+        continue;
+      }
+      const path = lc(m.escalationPath);
+      if (path && scopeTokens.some((t) => path.includes(t))) {
+        add(memberId(m), "ownership", `their escalation path names this scope`);
+      }
+    }
+  }
+  if (picked.size) return { targets: [...picked.values()], why };
+
+  // ── rung 3: expertise ──
+  if (scopeTokens.length) {
+    const scored = [];
+    for (const m of byId.values()) {
+      if (!engageable(m, me)) continue;
+      const hay = tokens([m.roleTitle, m.title, m.tagline, m.teamName].filter(Boolean).join(" "));
+      const hits = scopeTokens.filter((t) => hay.includes(t));
+      const strong = hits.some((t) => t.length >= 5);
+      // Two distinct tokens, or one substantial one. Below that it is noise.
+      if (hits.length >= 2 || strong) scored.push({ m, hits, score: hits.length + (strong ? 1 : 0) });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    for (const s of scored) {
+      add(memberId(s.m), "expertise", `their role/team matches this scope on ${s.hits.map((h) => `"${h}"`).join(", ")}`);
+    }
+  }
+  if (picked.size) return { targets: [...picked.values()], why };
+
+  // ── rung 4: supervisory ──
+  // Reached when nothing above named a REACHABLE person — including the case
+  // where the work named someone explicitly and that seat turned out to be
+  // archived. An addressee is still owed, and up the line is the defensible
+  // choice; sideways-to-a-guess is not.
+  const self = byId.get(String(me));
+  const supervisorId = (self && self.supervisorId) || o.supervisorId || null;
+  if (supervisorId) {
+    add(
+      supervisorId,
+      "supervisory",
+      "nobody reachable in the directory owns this scope, so it goes up the escalation path rather than sideways to a guess",
+    );
+  }
+
+  if (!picked.size) {
+    why.push(
+      `no target: the directory (${byId.size} entries) has nobody who owns "${(trigger.scope || work.title || "").slice(0, 80)}", and this seat has no supervisor edge`,
+    );
+  }
+  return { targets: [...picked.values()], why };
+}
+
+// ---------------------------------------------------------------------------
+// 3. WHERE — the cheapest surface that reaches everyone who must act
+// ---------------------------------------------------------------------------
+
+/**
+ * Choose the surface. PURE.
+ *
+ * The ordering is a cost ordering, not a preference: each step exposes more
+ * people or creates more persistent objects than the last.
+ *
+ *   reply_in_place  costs nothing — the conversation already exists and everyone
+ *                   who must act is already in it. ALWAYS first when it reaches
+ *                   the targets: opening a new room to answer a question someone
+ *                   asked you in an existing one is the single most common way
+ *                   agents make a mess.
+ *   dm              costs one person's attention, nobody else's.
+ *   existing_channel costs the attention of everyone already in that room, but
+ *                   creates nothing new. Smallest qualifying room wins.
+ *   new_room        costs everyone in it a permanent object. Requires ≥2 targets
+ *                   AND no existing room that already holds them, because a new
+ *                   room for one person is just a DM with extra ceremony.
+ *
+ * @param {object} o { work, targets, channels, me }
+ * @returns {{surface:string, channelId:string|null, threadRootId:string|null,
+ *            roomName:string|null, memberIds:string[], why:string}}
+ */
+export function chooseSurface(o = {}) {
+  const { work = {}, targets = [], channels = [], me = "" } = o;
+  const ids = targets.map((t) => t.memberId);
+  const origin = work.origin || {};
+  const index = (Array.isArray(channels) ? channels : []).map((c) => ({
+    id: String((c && (c.id || c.channelId)) || ""),
+    kind: String((c && (c.kind || c.channelKind)) || "").toUpperCase(),
+    name: String((c && (c.name || c.slug)) || ""),
+    members: new Set(
+      (Array.isArray(c && (c.memberIds || c.members)) ? c.memberIds || c.members : []).map((m) =>
+        String(m && typeof m === "object" ? m.memberId || m.id : m),
+      ),
+    ),
+  }));
+  const holdsAll = (ch) => ids.every((id) => ch.members.has(id));
+
+  // 1. The room the ask already lives in, when it holds everyone who must act.
+  if (origin.channelId) {
+    const originCh = index.find((c) => c.id === String(origin.channelId));
+    if (!originCh || originCh.members.size === 0 || holdsAll(originCh)) {
+      // Unknown membership for the origin room is treated as "it holds them" ONLY
+      // when the single target is the requester — that case is definitionally a
+      // reply, and refusing to reply because we could not read a roster would be
+      // absurd.
+      const soleRequester = ids.length === 1 && ids[0] === String(origin.requesterId || "");
+      if (originCh && holdsAll(originCh)) {
+        return {
+          surface: "reply_in_place",
+          channelId: String(origin.channelId),
+          threadRootId: origin.threadRootId || null,
+          roomName: null,
+          memberIds: ids,
+          why: `everyone who must act is already in the room this came from (${originCh.name || originCh.id}) — a new room would only move the conversation away from its context`,
+        };
+      }
+      if (soleRequester) {
+        return {
+          surface: "reply_in_place",
+          channelId: String(origin.channelId),
+          threadRootId: origin.threadRootId || null,
+          roomName: null,
+          memberIds: ids,
+          why: "the only person who must act is the person who asked, in the thread they asked in",
+        };
+      }
+    }
+  }
+
+  // 2. One person, no shared audience needed.
+  if (ids.length === 1) {
+    return {
+      surface: "dm",
+      channelId: null,
+      threadRootId: null,
+      roomName: null,
+      memberIds: ids,
+      why: "one person must act and nobody else needs to watch — a 1:1 costs exactly one person's attention",
+    };
+  }
+
+  // 3. An existing room that already holds all of them. Smallest wins: the
+  //    fewest bystanders. A tie prefers a private/group room over a public one.
+  const candidates = index
+    .filter((c) => c.id && c.members.size > 0 && holdsAll(c) && (!me || c.members.has(String(me))))
+    .sort((a, b) => a.members.size - b.members.size);
+  if (candidates.length) {
+    const ch = candidates[0];
+    return {
+      surface: "existing_channel",
+      channelId: ch.id,
+      threadRootId: null,
+      roomName: ch.name || null,
+      memberIds: ids,
+      why: `${ch.name || ch.id} already holds all ${ids.length} of them (${ch.members.size} members — the smallest room that does), so nothing new needs creating`,
+    };
+  }
+
+  // 4. A new room. The expensive option, and it says so.
+  const durable = work.durable === true;
+  return {
+    surface: "new_room",
+    channelId: null,
+    threadRootId: null,
+    roomName: (work.title || "").slice(0, 100) || "Needs a decision",
+    memberIds: ids,
+    durableChannel: durable,
+    why: `${ids.length} people must act together and no room already holds them${durable ? "; the work is durable, so a named channel rather than an ad-hoc group" : ""}`,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 4. WHAT IT SAYS — a template, not an LLM call
+// ---------------------------------------------------------------------------
+
+/**
+ * Compose the ask. Deterministic and cheap ON PURPOSE.
+ *
+ * The daemon's holding-message path proves the alternative: generating one
+ * courtesy sentence through a `claude --print` child under a 60s cap failed 20
+ * times out of 32 on a memory-pressured machine, and every failure was silent.
+ * An engagement that only happens when an LLM spawn wins a race is not an
+ * engagement mechanism. This cannot time out, cannot cost anything, and cannot
+ * hallucinate a name.
+ *
+ * The shape is fixed because the reader's job is fixed: what stopped, what I
+ * need from you, what I already tried, and — always last — the single question.
+ *
+ * @param {object} o { work, trigger, targets, surface }
+ * @returns {string}
+ */
+export function composeAsk(o = {}) {
+  const { work = {}, trigger = {}, targets = [] } = o;
+  const title = String(work.title || work.id || "this piece of work").trim();
+  const lines = [];
+
+  const heads = {
+    blocked_on_other: `**Blocked:** ${title}`,
+    irreversible_or_external: `**Needs your go-ahead:** ${title}`,
+    mandatory_review: `**Ready for review:** ${title}`,
+    commitment_at_risk: `**Heads-up on ${title}**`,
+  };
+  lines.push(heads[trigger.trigger] || `**${title}**`);
+  lines.push("");
+
+  if (work.summary) lines.push(String(work.summary).trim());
+  if (trigger.detail) lines.push(`Where it stopped: ${String(trigger.detail).trim()}`);
+
+  if (Array.isArray(work.tried) && work.tried.length) {
+    lines.push("");
+    lines.push("What I've already tried:");
+    for (const t of work.tried.slice(0, 5)) lines.push(`- ${String(t).trim()}`);
+  }
+
+  const asks = {
+    blocked_on_other: "I can't clear this myself.",
+    irreversible_or_external: "I'm not taking this step without a yes — it can't be undone.",
+    mandatory_review: "It needs your sign-off before it lands.",
+    commitment_at_risk: "You asked for this and it isn't going to land as promised, so you're hearing it from me rather than finding out.",
+  };
+  lines.push("");
+  lines.push(asks[trigger.trigger] || "");
+
+  const question = String(work.question || "").trim();
+  const options = (Array.isArray(work.options) ? work.options : []).map((x) => String(x).trim()).filter(Boolean);
+  if (question) {
+    lines.push("");
+    lines.push(question);
+    if (options.length >= 2) for (const opt of options.slice(0, 5)) lines.push(`- ${opt}`);
+  } else if (targets.length) {
+    lines.push("");
+    lines.push(`@${targets.map((t) => t.name).join(" @")} — what would you like me to do?`);
+  }
+
+  if (work.link) {
+    lines.push("");
+    lines.push(String(work.link));
+  }
+  return lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+}
+
+// ---------------------------------------------------------------------------
+// 5. THE DECISION
+// ---------------------------------------------------------------------------
+
+/**
+ * Decide whether to engage anyone, who, and where. PURE — no clock of its own,
+ * no disk, no network. Everything it needs is injected.
+ *
+ * @param {object} work {
+ *   id, title, summary, scope?, question?, options?, link?, tried?[],
+ *   state: "in_progress"|"blocked"|"failed"|"done",
+ *   origin?:     { surface?, channelId?, threadRootId?, requesterId? },
+ *   blocker?:    { kind:"decision"|"access"|"information"|"approval"|"capacity",
+ *                  scope?, detail?, ownerId? },
+ *   selfServeExhausted?: boolean,   // REQUIRED true for the blocked trigger
+ *   risk?:       { irreversible?, external?, financial? },
+ *   review?:     { required?, requested?, kind?, reviewerId? },
+ *   commitment?: { toMemberId, dueAtMs?, atRisk? },
+ *   interestedParties?: [memberId], // considered, deliberately not pinged
+ *   durable?: boolean               // a new room should be a named channel
+ * }
+ * @param {object} ctx {
+ *   me, directory:[member], channels:[channel], ledger:[row], nowMs, limits?,
+ *   supervisorId?, maxTargets?
+ * }
+ * @returns {object} decision
+ */
+export function decideEngagement(work = {}, ctx = {}) {
+  const nowMs = Number.isFinite(ctx.nowMs) ? ctx.nowMs : Date.now();
+  const workId = String(work.id || work.key || "").trim();
+  const why = [];
+  const degraded = [].concat(ctx.degraded || []);
+
+  const base = {
+    engage: false,
+    trigger: null,
+    reasonCode: null,
+    reason: null,
+    targets: [],
+    surface: "none",
+    channelId: null,
+    threadRootId: null,
+    roomName: null,
+    mentions: [],
+    body: null,
+    workId,
+    dedupeKey: null,
+    guardrail: null,
+    why,
+    degraded,
+    consideredNotEngaged: [],
+    nowMs,
+  };
+
+  // ── whether ──
+  const { fired, suppressed } = evaluateTriggers(work);
+  for (const s of suppressed) why.push(`trigger ${s.trigger} did not fire — ${s.code}: ${s.detail}`);
+
+  // The FYI class, named explicitly. These people were CONSIDERED and declined,
+  // which is a different and much more defensible statement than never having
+  // thought about them.
+  const fyi = (Array.isArray(work.interestedParties) ? work.interestedParties : []).map(String).filter(Boolean);
+  if (fyi.length) {
+    base.consideredNotEngaged = fyi;
+    why.push(
+      `${fyi.length} interested part${fyi.length === 1 ? "y" : "ies"} (${fyi.join(", ")}) considered and NOT messaged: nothing they do changes because of this, so it belongs on the board where they can pull it, not in their DMs`,
+    );
+  }
+
+  if (!fired.length) {
+    const reasonCode = suppressed.length ? suppressed[0].code : "self_contained";
+    if (!suppressed.length) {
+      // A `self_contained` row with an empty `why` is indistinguishable from a
+      // judgement that never ran. Say what was examined, so the row proves the
+      // threshold was applied rather than merely asserting an outcome.
+      why.push(
+        `no trigger fired: state=${lc(work.state) || "in_progress"}, ` +
+          `blocker=${work.blocker ? lc(work.blocker.kind) || "unspecified" : "none"}, ` +
+          `risk=${["irreversible", "external", "financial"].filter((k) => (work.risk || {})[k]).join("+") || "none"}, ` +
+          `review=${work.review && work.review.required ? "required" : "none"}, ` +
+          `commitment=${work.commitment && work.commitment.atRisk ? "at risk" : "none"} — ` +
+          "nobody's action or consent is a precondition, so nobody is interrupted",
+      );
+    }
+    return {
+      ...base,
+      reasonCode,
+      reason:
+        reasonCode === "self_contained"
+          ? "nobody's action is a precondition here — the work proceeds on its own"
+          : suppressed[0].detail,
+    };
+  }
+
+  const trigger = fired[0];
+  base.trigger = trigger.trigger;
+  why.push(`trigger ${trigger.trigger} (${trigger.code}): ${trigger.detail}`);
+  for (const extra of fired.slice(1)) why.push(`also firing: ${extra.trigger} (${extra.code})`);
+
+  // ── who ──
+  const resolved = resolveTargets({
+    work,
+    trigger,
+    directory: ctx.directory || [],
+    me: ctx.me || "",
+    supervisorId: ctx.supervisorId,
+    maxTargets: ctx.maxTargets,
+  });
+  why.push(...resolved.why);
+  if (!resolved.targets.length) {
+    // Loud, not silent. A blocked piece of work with nobody to ask is a
+    // provisioning gap (no owner, no supervisor edge) and it must read as one.
+    return {
+      ...base,
+      reasonCode: "unroutable",
+      reason: `${trigger.trigger} fired but nobody in the directory owns this and this seat has no supervisor — the ask has no addressee, which is an org gap, not a quiet no`,
+      degraded: degraded.concat(["engagement_unroutable"]),
+    };
+  }
+
+  // ── where ──
+  const place = chooseSurface({ work, targets: resolved.targets, channels: ctx.channels || [], me: ctx.me });
+  why.push(`surface ${place.surface}: ${place.why}`);
+
+  const dedupeKey = dedupeKeyFor({ workId, reasonCode: trigger.code, targets: resolved.targets });
+
+  // ── guardrails ──
+  const guard = checkGuardrails({
+    rows: ctx.ledger || [],
+    nowMs,
+    dedupeKey,
+    workId,
+    targets: resolved.targets,
+    createsRoom: place.surface === "new_room",
+    limits: ctx.limits || DEFAULT_LIMITS,
+  });
+  if (!guard.allowed) {
+    why.push(`guardrail ${guard.code}: ${guard.detail}`);
+    return {
+      ...base,
+      trigger: trigger.trigger,
+      reasonCode: guard.code,
+      reason: guard.detail,
+      targets: resolved.targets,
+      surface: place.surface,
+      dedupeKey,
+      guardrail: { code: guard.code, detail: guard.detail, counts: guard.counts },
+    };
+  }
+
+  const body = composeAsk({ work, trigger, targets: resolved.targets, surface: place.surface });
+
+  return {
+    ...base,
+    engage: true,
+    trigger: trigger.trigger,
+    reasonCode: trigger.code,
+    reason: trigger.detail,
+    targets: resolved.targets,
+    surface: place.surface,
+    channelId: place.channelId,
+    threadRootId: place.threadRootId,
+    roomName: place.roomName,
+    durableChannel: place.durableChannel === true,
+    memberIds: place.memberIds,
+    // Everyone who must act gets tagged. This is the whole point of the mention
+    // fix in messaging.mjs: an unmentioned name in a busy room is not an ask.
+    mentions: resolved.targets.map((t) => ({ memberId: t.memberId })),
+    body,
+    dedupeKey,
+    // Which send this is for this ask. The dedupe key is timeless by design —
+    // that is what makes the re-engage window enforceable — so the ordinal is
+    // what keeps a re-ask from colliding with the original on hq's server-side
+    // message dedupe and posting nothing.
+    attempt: guard.attempt || 1,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// 6. DOING IT
+// ---------------------------------------------------------------------------
+
+/**
+ * Load the context `decideEngagement` needs. Every leg fails open INDEPENDENTLY
+ * and says so — a directory we could not read must not look like an empty org,
+ * because an empty org routes everything to `unroutable` and the operator would
+ * read that as "nobody owns this" rather than "the read failed".
+ *
+ * @param {object} o { cfg, agentRoot, me, fetchImpl?, nowMs?, limits? }
+ * @returns {Promise<object>} ctx for decideEngagement
+ */
+export async function loadEngagementContext(o = {}) {
+  const degraded = [];
+  let directory = [];
+  let channels = [];
+
+  try {
+    const { call, configFromAgent } = await import("./client.mjs");
+    const c = configFromAgent(o.cfg || {});
+    if (c.base) {
+      // The WHOLE roster, deliberately unfiltered. hq's `status` filter takes the
+      // Prisma enum (`ACTIVE`/`BENCH`/`INACTIVE`, uppercase) and rejects anything
+      // else, and filtering server-side would also hide the fact that the person
+      // who owns a scope is benched. `engageable()` makes that call locally and
+      // RECORDS the skip, which is the difference between "we chose not to ping
+      // an inactive seat" and "nobody owns this".
+      const frame = await call("member.list", {}, { base: c.base, token: c.token, fetchImpl: o.fetchImpl });
+      if (frame && frame.ok && frame.result) {
+        const rows = Array.isArray(frame.result) ? frame.result : frame.result.members;
+        if (Array.isArray(rows)) directory = rows;
+        else degraded.push("directory_unexpected_shape");
+      } else {
+        degraded.push(`directory_read_failed:${(frame && frame.error && frame.error.code) || "unknown"}`);
+      }
+    } else {
+      degraded.push("directory_unavailable:no_org_base");
+    }
+  } catch (err) {
+    degraded.push(`directory_read_threw:${(err && err.message) || err}`);
+  }
+
+  try {
+    const { listChannels } = await import("./messaging.mjs");
+    channels = await listChannels({ cfg: o.cfg, fetchImpl: o.fetchImpl });
+    if (!Array.isArray(channels)) { channels = []; degraded.push("channels_unexpected_shape"); }
+  } catch (err) {
+    degraded.push(`channels_read_threw:${(err && err.message) || err}`);
+  }
+
+  const led = loadEngagements({ agentRoot: o.agentRoot, path: o.ledgerPath });
+  degraded.push(...led.degraded);
+
+  return {
+    me: o.me || "",
+    directory,
+    channels,
+    ledger: led.rows,
+    nowMs: Number.isFinite(o.nowMs) ? o.nowMs : Date.now(),
+    limits: o.limits || DEFAULT_LIMITS,
+    supervisorId: o.supervisorId,
+    degraded,
+  };
+}
+
+/**
+ * Execute a decision — including the decisions that engage nobody, which are
+ * recorded exactly as loudly as the ones that do.
+ *
+ * The send always goes through `messaging.sendMessage`, which runs the shared
+ * outbound send-gate before the wire. That is not bypassable here and should not
+ * be: an engagement is a real message to a real person. A gate refusal is
+ * recorded as `send_blocked` with the policy reason attached — the one thing it
+ * must never be is a quiet no-op, because the whole point of this module is that
+ * an unspoken ask is a bug.
+ *
+ * @param {object} decision from `decideEngagement`
+ * @param {object} o { cfg, agentRoot, fetchImpl?, nowMs?, ledgerPath?, deps? }
+ * @returns {Promise<{ok:boolean, engaged:boolean, surface:string,
+ *                    channelId:string|null, outcome:string, error:string|null,
+ *                    decision:object}>}
+ */
+export async function runEngagement(decision, o = {}) {
+  const nowMs = Number.isFinite(o.nowMs) ? o.nowMs : (decision && decision.nowMs) || Date.now();
+  const deps = o.deps || {};
+  const record = (outcome, extra = {}) => {
+    appendEngagement(
+      {
+        workId: decision.workId,
+        trigger: decision.trigger,
+        reasonCode: decision.reasonCode,
+        reason: decision.reason,
+        dedupeKey: decision.dedupeKey,
+        engaged: outcome === "engaged",
+        outcome,
+        surface: extra.surface || decision.surface,
+        channelId: extra.channelId || decision.channelId,
+        roomCreated: !!extra.roomCreated,
+        targets: decision.targets,
+        why: decision.why,
+      },
+      { agentRoot: o.agentRoot, path: o.ledgerPath, nowMs },
+    );
+  };
+
+  if (!decision || typeof decision !== "object") {
+    return { ok: false, engaged: false, surface: "none", channelId: null, outcome: "none", error: "no decision", decision: null };
+  }
+
+  // A considered non-engagement. Recorded, then done.
+  if (!decision.engage) {
+    record(
+      decision.guardrail
+        ? decision.guardrail.code
+        : decision.reasonCode === "unroutable"
+          ? "unroutable"
+          : "none",
+    );
+    return {
+      ok: true,
+      engaged: false,
+      surface: "none",
+      channelId: null,
+      outcome: decision.reasonCode || "none",
+      error: null,
+      decision,
+    };
+  }
+
+  const messaging = deps.messaging || (await import("./messaging.mjs"));
+  const sendOpts = { cfg: o.cfg, agentRoot: o.agentRoot, fetchImpl: o.fetchImpl, ...(o.sendOpts || {}) };
+
+  // Resolve the room the ask lands in.
+  let channelId = decision.channelId;
+  let roomCreated = false;
+  if (decision.surface === "dm") {
+    const r = await messaging.openDm({ memberId: decision.targets[0].memberId }, sendOpts);
+    if (!r.ok) {
+      const err = (r.frame && r.frame.error && (r.frame.error.message || r.frame.error.code)) || "could not open a DM";
+      record("send_failed");
+      return { ok: false, engaged: false, surface: decision.surface, channelId: null, outcome: "send_failed", error: String(err), decision };
+    }
+    channelId = r.channelId;
+    roomCreated = r.created;
+  } else if (decision.surface === "new_room") {
+    const memberIds = decision.memberIds || decision.targets.map((t) => t.memberId);
+    const r = decision.durableChannel
+      ? await messaging.createChannel(
+          {
+            slug: slugify(decision.roomName || decision.workId || "engagement"),
+            name: decision.roomName || "Needs a decision",
+            kind: "PRIVATE",
+            topic: decision.reason || undefined,
+            members: memberIds,
+          },
+          sendOpts,
+        )
+      : await messaging.openConversation({ memberIds, name: decision.roomName || undefined }, sendOpts);
+    if (!r.ok) {
+      const err = (r.frame && r.frame.error && (r.frame.error.message || r.frame.error.code)) || "could not open a room";
+      record("send_failed");
+      return { ok: false, engaged: false, surface: decision.surface, channelId: null, outcome: "send_failed", error: String(err), decision };
+    }
+    channelId = r.channelId;
+    roomCreated = true;
+  }
+
+  if (!channelId) {
+    record("send_failed");
+    return { ok: false, engaged: false, surface: decision.surface, channelId: null, outcome: "send_failed", error: "no channel resolved for the engagement", decision };
+  }
+
+  const res = await messaging.sendMessage(
+    {
+      channel: channelId,
+      body: decision.body,
+      mentions: decision.mentions,
+      ...(decision.threadRootId ? { threadId: decision.threadRootId } : {}),
+      // Stable on the ask's identity AND on which send this is.
+      //
+      // hq de-dupes on (org, channel, clientMsgId) and returns the EXISTING
+      // message verbatim rather than erroring, so an id keyed on the ask alone
+      // makes the re-ask — the whole reason `reengageAfterMs` exists, fired six
+      // hours later when silence has started to look like the agent forgot —
+      // post absolutely nothing, while `frame.ok === true` reports it delivered
+      // and the ledger records an engagement that never happened. The attempt
+      // ordinal separates distinct asks; a genuine transport RETRY within one
+      // attempt reuses the id, which is the dedupe doing its job.
+      idempotencyId: `engage-${decision.dedupeKey}-${decision.attempt || 1}`,
+    },
+    sendOpts,
+  );
+
+  if (!res || res.ok === false) {
+    const blocked = !!(res && res.blocked);
+    const err = (res && res.error && (res.error.message || res.error.code)) || "messaging.send failed";
+    record(blocked ? "send_blocked" : "send_failed", { channelId, roomCreated });
+    return {
+      ok: false,
+      engaged: false,
+      surface: decision.surface,
+      channelId,
+      outcome: blocked ? "send_blocked" : "send_failed",
+      error: String(err),
+      decision,
+    };
+  }
+
+  record("engaged", { channelId, roomCreated });
+  return { ok: true, engaged: true, surface: decision.surface, channelId, outcome: "engaged", error: null, decision };
+}
+
+/** hq's channel slug grammar: lowercase alphanumerics + hyphens, ≤80. */
+function slugify(s) {
+  const base = lc(s).replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 72);
+  return base ? `x-${base}`.slice(0, 80) : `x-${Date.now().toString(36)}`;
+}
+
+/**
+ * Decide and, if warranted, act — the one call a caller should need.
+ * Loads the context, decides, records, executes.
+ *
+ * @param {object} work
+ * @param {object} o { cfg, agentRoot, me, fetchImpl?, nowMs?, ctx?, limits? }
+ * @returns {Promise<object>} the run result, with `.decision` attached
+ */
+export async function engage(work, o = {}) {
+  const ctx = o.ctx || (await loadEngagementContext(o));
+  const decision = decideEngagement(work, ctx);
+  return runEngagement(decision, o);
+}
+
+export default {
+  TRIGGERS,
+  SURFACES,
+  evaluateTriggers,
+  resolveTargets,
+  chooseSurface,
+  composeAsk,
+  decideEngagement,
+  loadEngagementContext,
+  runEngagement,
+  engage,
+};