@cohortapp/agent-sdk 2.3.2 → 2.4.0

package/lib/org/inbound/directedness.test.mjs

@@ -0,0 +1,543 @@
+/**
+ * directedness.test.mjs — the pure half of wide org inbound.
+ *
+ * Every family gets a POSITIVE case (this is mine, and here is the typed reason)
+ * and a NEGATIVE case. The negatives are the point: the org event feed is
+ * org-wide, so a resolver that guesses "yes" makes an agent barge into other
+ * people's private conversations. The load-bearing one —
+ * "an event in someone else's private room must NEVER be directed" — is asserted
+ * three ways: not a member, not visible, and roster unknown.
+ *
+ * Run: node --test lib/org/inbound/directedness.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  classifyEvent,
+  resolveDirected,
+  coordsOf,
+  matchesMyName,
+  taskIdFromFileKey,
+  needsSpaceProbe,
+} from "./directedness.mjs";
+
+const ME = "M-me";
+const THEM = "M-them";
+
+/** A minimal Facts object; every field opt-in so a test states only what it means. */
+function facts(over = {}) {
+  return {
+    me: ME,
+    myNames: [],
+    channels: new Map(),
+    visibleChannelIds: new Set(),
+    memberChannelIds: new Set(),
+    channelPages: new Map(),
+    myThreadRootIds: new Set(),
+    taskRole: null,
+    tasks: null,
+    decisions: null,
+    decisionVoices: new Map(),
+    escalations: null,
+    approvals: null,
+    fileAcl: null,
+    degraded: [],
+    ...over,
+  };
+}
+
+/** Register a channel as visible (+ a member when non-PUBLIC). */
+function withChannel(f, id, kind) {
+  f.channels.set(id, { id, kind, name: id, slug: id });
+  f.visibleChannelIds.add(id);
+  if (kind !== "PUBLIC") f.memberChannelIds.add(id);
+  return f;
+}
+
+/** Put a message on the hydrated page for a channel. */
+function withMessage(f, channelId, msg) {
+  const page = f.channelPages.get(channelId) || { byId: new Map(), messages: [] };
+  page.byId.set(String(msg.id), msg);
+  page.messages.push(msg);
+  f.channelPages.set(channelId, page);
+  return f;
+}
+
+function ev(over) {
+  return { seq: 1, at: "2026-08-11T00:00:00.000Z", actor: THEM, ...over };
+}
+
+// ---------------------------------------------------------------------------
+// coordsOf — modern + legacy event shapes
+// ---------------------------------------------------------------------------
+
+test("coordsOf reads {family,kind} and the legacy dotted kind", () => {
+  assert.deepEqual(coordsOf({ family: "board", kind: "item.assigned" }), {
+    family: "board",
+    kind: "item.assigned",
+  });
+  assert.deepEqual(coordsOf({ kind: "messaging.send" }), {
+    family: "messaging",
+    kind: "send",
+  });
+});
+
+// ---------------------------------------------------------------------------
+// THE SAFETY INVARIANT — someone else's private room
+// ---------------------------------------------------------------------------
+
+test("NEGATIVE: a DM between two other people is never directed (not a member)", () => {
+  const f = facts();
+  // The room is not in my roster at all — hq only returns a DM to its members.
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "msg-1", payload: { actor: THEM, channelId: "C-theirs", channelKind: "DM" } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "channel_not_visible");
+});
+
+test("NEGATIVE: a DM visible-but-not-member is refused (belt and braces)", () => {
+  const f = facts();
+  // Deliberately inconsistent state: visible without membership. Must still refuse.
+  f.channels.set("C-theirs", { id: "C-theirs", kind: "DM" });
+  f.visibleChannelIds.add("C-theirs");
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-theirs", channelKind: "DM" } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "not_a_member");
+});
+
+test("NEGATIVE: roster unreadable → private rooms stay closed, not open", () => {
+  const f = facts({ visibleChannelIds: null, memberChannelIds: null });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-x", channelKind: "DM" } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "membership_unknown");
+});
+
+test("NEGATIVE: a PRIVATE space I am not in is refused before any mention probe", () => {
+  const f = facts();
+  f.channels.set("C-priv", { id: "C-priv", kind: "PRIVATE" });
+  f.visibleChannelIds.add("C-priv"); // visible but NOT a member
+  withMessage(f, "C-priv", { id: "m9", authorId: THEM, body: "hey", mentions: [ME] });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m9", payload: { actor: THEM, channelId: "C-priv", channelKind: "PRIVATE", mentionCount: 1 } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false, "a mention in a private space I am not in must not reach me");
+  assert.equal(v.reason, "not_a_member");
+});
+
+test("NEGATIVE: my own echo is never inbound", () => {
+  const f = withChannel(facts(), "C-dm", "DM");
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", actor: ME, entity_id: "m1", payload: { actor: ME, channelId: "C-dm", channelKind: "DM" } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).reason, "own_echo");
+});
+
+// ---------------------------------------------------------------------------
+// messaging — DM / mention / thread / ambient
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: a message in a DM I belong to is directed (reason dm)", () => {
+  const f = withChannel(facts(), "C-dm", "DM");
+  withMessage(f, "C-dm", { id: "m1", authorId: THEM, body: "ping" });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM", mentionCount: 0, threaded: false } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ d: v.directed, s: v.surface, r: v.reason }, { d: true, s: "dm", r: "dm" });
+});
+
+test("POSITIVE: an @mention in a PUBLIC space is directed (THE headline gap)", () => {
+  const f = withChannel(facts(), "C-pub", "PUBLIC");
+  withMessage(f, "C-pub", { id: "m2", authorId: THEM, body: "@Isla can you look?", mentions: [ME] });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m2", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 1, threaded: false } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ d: v.directed, s: v.surface, r: v.reason }, { d: true, s: "mention", r: "mention" });
+});
+
+test("POSITIVE: an @mention in a PRIVATE space I AM in is directed", () => {
+  const f = withChannel(facts(), "C-priv", "PRIVATE");
+  withMessage(f, "C-priv", { id: "m3", authorId: THEM, body: "over to you", mentions: [ME] });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m3", payload: { actor: THEM, channelId: "C-priv", channelKind: "PRIVATE", mentionCount: 1, threaded: false } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).surface, "mention");
+});
+
+test("POSITIVE: a reply in a thread I have spoken in is directed (reason thread)", () => {
+  const f = withChannel(facts(), "C-pub", "PUBLIC");
+  f.myThreadRootIds.add("root-1");
+  withMessage(f, "C-pub", { id: "m4", authorId: THEM, body: "and one more thing", threadRootId: "root-1", mentions: [] });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m4", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 0, threaded: true } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "thread_reply", r: "thread" });
+});
+
+test("NEGATIVE: ambient public chatter that names nobody is not directed", () => {
+  const f = withChannel(facts(), "C-pub", "PUBLIC");
+  withMessage(f, "C-pub", { id: "m5", authorId: THEM, body: "standup at 10", mentions: [] });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m5", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 0, threaded: false } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false);
+  // The redacted counts alone prove it — no page was needed.
+  assert.equal(v.reason, "no_mentions_not_threaded");
+});
+
+test("NEGATIVE: a thread reply in a thread I am NOT in is not directed", () => {
+  const f = withChannel(facts(), "C-pub", "PUBLIC");
+  withMessage(f, "C-pub", { id: "m6", authorId: THEM, body: "sure", threadRootId: "root-other", mentions: [] });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m6", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 0, threaded: true } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).directed, false);
+});
+
+test("needsSpaceProbe: counts prove it, unless prose-name matching is on", () => {
+  const cheap = { hints: { mentionCount: 0, threaded: false } };
+  assert.equal(needsSpaceProbe(cheap, {}), false);
+  assert.equal(needsSpaceProbe(cheap, { myNames: ["Isla"] }), null, "name matching needs the body");
+  assert.equal(needsSpaceProbe({ hints: { mentionCount: 2, threaded: false } }, {}), true);
+  assert.equal(needsSpaceProbe({ hints: {} }, {}), null, "absent counts → probe to be safe");
+});
+
+test("POSITIVE: prose-name mention in a public space when myNames is supplied", () => {
+  const f = withChannel(facts({ myNames: ["Isla"] }), "C-pub", "PUBLIC");
+  withMessage(f, "C-pub", { id: "m7", authorId: THEM, body: "Isla, can you take this?", mentions: [] });
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m7", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 0, threaded: false } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "mention", r: "named" });
+});
+
+// ---------------------------------------------------------------------------
+// calling
+// ---------------------------------------------------------------------------
+
+test("POSITIVE/NEGATIVE: a call in my room is directed; in a room I am not in it is not", () => {
+  const f = withChannel(facts(), "C-dm", "DM");
+  const mine = classifyEvent(
+    ev({ family: "calling", kind: "call.started", entity_id: "call-1", payload: { actor: THEM, callId: "call-1", channelId: "C-dm", topic: "sync" } }),
+  );
+  assert.equal(resolveDirected(mine, ME, f).surface, "call");
+
+  const theirs = classifyEvent(
+    ev({ family: "calling", kind: "call.started", entity_id: "call-2", payload: { actor: THEM, callId: "call-2", channelId: "C-other" } }),
+  );
+  assert.equal(resolveDirected(theirs, ME, f).directed, false);
+});
+
+test("POSITIVE: a call whose payload names me as an invitee is directed", () => {
+  const c = classifyEvent(
+    ev({ family: "calling", kind: "call.invited", entity_id: "call-3", payload: { actor: THEM, callId: "call-3", invitees: [ME] } }),
+  );
+  const v = resolveDirected(c, ME, facts());
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "call", r: "participant" });
+});
+
+// ---------------------------------------------------------------------------
+// board
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: board.item.assigned naming me needs no join at all", () => {
+  const c = classifyEvent(
+    ev({ family: "board", kind: "item.assigned", entity_id: "T-1", payload: { actor: THEM, assignee: ME } }),
+  );
+  const v = resolveDirected(c, ME, facts());
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "task_assigned", r: "assignee" });
+});
+
+test("POSITIVE: a comment on a task I own is directed (reason assignee)", () => {
+  const f = facts({ taskRole: new Map([["T-1", "assignee"]]) });
+  const c = classifyEvent(
+    ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM, kind: "human" } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "task_comment", r: "assignee" });
+});
+
+test("POSITIVE: a comment on a task I REVIEW is directed (reason reviewer)", () => {
+  const f = facts({ taskRole: new Map([["T-2", "reviewer"]]) });
+  const c = classifyEvent(ev({ family: "board", kind: "board.blocked", entity_id: "T-2", payload: { actor: THEM, reason: "waiting" } }));
+  assert.equal(resolveDirected(c, ME, f).reason, "reviewer");
+});
+
+test("NEGATIVE: a comment on somebody else's task is not directed", () => {
+  const f = facts({ taskRole: new Map([["T-1", "assignee"]]) });
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-99", payload: { actor: THEM } }));
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "not_my_task");
+});
+
+test("NEGATIVE: board facts unreadable → not directed, and the reason says so", () => {
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }));
+  assert.equal(resolveDirected(c, ME, facts()).reason, "board_unknown");
+});
+
+test("NEGATIVE: an assignment to SOMEONE ELSE is not directed at me", () => {
+  const c = classifyEvent(
+    ev({ family: "board", kind: "item.assigned", entity_id: "T-7", payload: { actor: ME, assignee: THEM } }),
+  );
+  // (actor is me here, so it is also my own echo — assert with a third party.)
+  const c2 = classifyEvent(
+    ev({ family: "board", kind: "item.assigned", entity_id: "T-7", actor: "M-boss", payload: { actor: "M-boss", assignee: THEM } }),
+  );
+  assert.equal(resolveDirected(c, ME, facts()).directed, false);
+  assert.equal(resolveDirected(c2, ME, facts()).directed, false);
+});
+
+// ---------------------------------------------------------------------------
+// file (chat attachment) + files (workspace doc)
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: a file comment in a room I belong to is directed", () => {
+  const f = withChannel(facts(), "C-team", "PRIVATE");
+  const c = classifyEvent(
+    ev({ family: "file", kind: "file.commented", entity_id: "fc-1", payload: { fileKey: "message-attachment:x", channelId: "C-team", authorId: THEM } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "file_comment", r: "channel" });
+});
+
+test("NEGATIVE: a file comment in a room I am not in is not directed", () => {
+  const f = facts();
+  const c = classifyEvent(
+    ev({ family: "file", kind: "file.commented", entity_id: "fc-2", payload: { fileKey: "message-attachment:y", channelId: "C-theirs", authorId: THEM } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).directed, false);
+});
+
+test("POSITIVE: a comment on MY task's attachment survives a missing channelId", () => {
+  const f = facts({ taskRole: new Map([["T-5", "assignee"]]) });
+  const c = classifyEvent(
+    ev({ family: "file", kind: "file.commented", entity_id: "fc-3", payload: { fileKey: "task-attachment:T-5:doc.pdf", channelId: null, authorId: THEM } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).reason, "assignee");
+});
+
+test("taskIdFromFileKey recovers the task, and only for task attachments", () => {
+  assert.equal(taskIdFromFileKey("task-attachment:T-5:doc.pdf"), "T-5");
+  assert.equal(taskIdFromFileKey("message-attachment:abc"), "");
+  assert.equal(taskIdFromFileKey(undefined), "");
+});
+
+test("POSITIVE/NEGATIVE: doc comments follow ownership and shares", () => {
+  const owned = facts({ fileAcl: new Map([["F-1", { ownerId: ME, shared: false }]]) });
+  const shared = facts({ fileAcl: new Map([["F-2", { ownerId: THEM, shared: true }]]) });
+  const named = facts({ fileAcl: new Map([["F-3", { ownerId: THEM, shared: false, mentionsMe: true }]]) });
+  const foreign = facts({ fileAcl: new Map([["F-4", { ownerId: THEM, shared: false }]]) });
+  const mk = (id) => classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: id, payload: { name: "spec", commentId: "dc1" } }));
+
+  assert.equal(resolveDirected(mk("F-1"), ME, owned).reason, "owner");
+  assert.equal(resolveDirected(mk("F-2"), ME, shared).reason, "shared");
+  assert.equal(resolveDirected(mk("F-3"), ME, named).reason, "named");
+  assert.equal(resolveDirected(mk("F-4"), ME, foreign).directed, false);
+  // A doc that files.get could not see at all is NOT_FOUND → never mine.
+  assert.equal(resolveDirected(mk("F-9"), ME, foreign).reason, "file_not_visible");
+});
+
+// ---------------------------------------------------------------------------
+// decision
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: a comment on a decision I proposed is directed (reason proposer)", () => {
+  const f = facts({ decisions: new Map([["D-1", { id: "D-1", title: "Ship it", proposedBy: ME }]]) });
+  const c = classifyEvent(
+    ev({ family: "decision", kind: "decision.comment", entity_id: "D-1", payload: { commentId: "dc1", authorId: THEM, length: 10 } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "decision", r: "proposer" });
+});
+
+test("POSITIVE: an adjustment on a decision I have commented on is directed", () => {
+  const f = facts({
+    decisions: new Map([["D-2", { id: "D-2", proposedBy: THEM }]]),
+    decisionVoices: new Map([["D-2", new Set([ME, THEM])]]),
+  });
+  const c = classifyEvent(
+    ev({ family: "decision", kind: "decision.adjustment_requested", entity_id: "D-2", payload: { commentId: "dc2", authorId: THEM } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).reason, "commenter");
+});
+
+test("NEGATIVE: a decision I have nothing to do with is not directed", () => {
+  const f = facts({
+    decisions: new Map([["D-3", { id: "D-3", proposedBy: THEM }]]),
+    decisionVoices: new Map([["D-3", new Set([THEM])]]),
+  });
+  const c = classifyEvent(ev({ family: "decision", kind: "decision.comment", entity_id: "D-3", payload: { authorId: THEM } }));
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "not_my_decision");
+});
+
+// ---------------------------------------------------------------------------
+// escalation
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: an escalation waiting on me is directed", () => {
+  const f = facts({ escalations: new Map([["E-1", { id: "E-1", title: "prod down", waitingOn: ME }]]) });
+  const c = classifyEvent(
+    ev({ family: "escalation", kind: "escalation.raised", entity_id: "E-1", payload: { actor: THEM, severity: "high", taskId: null, channelId: null } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "escalation", r: "waiting_on" });
+});
+
+test("POSITIVE: an escalation on my task is directed", () => {
+  const f = facts({
+    escalations: new Map([["E-2", { id: "E-2", taskId: "T-1" }]]),
+    taskRole: new Map([["T-1", "assignee"]]),
+  });
+  const c = classifyEvent(
+    ev({ family: "escalation", kind: "escalation.raised", entity_id: "E-2", payload: { actor: THEM, taskId: "T-1" } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).reason, "assignee");
+});
+
+test("NEGATIVE: an escalation in a room I am not in is not directed", () => {
+  const f = facts({ escalations: new Map([["E-3", { id: "E-3", channelId: "C-theirs" }]]), taskRole: new Map() });
+  const c = classifyEvent(
+    ev({ family: "escalation", kind: "escalation.raised", entity_id: "E-3", payload: { actor: THEM, channelId: "C-theirs" } }),
+  );
+  assert.equal(resolveDirected(c, ME, f).directed, false);
+});
+
+// ---------------------------------------------------------------------------
+// approval
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: an approval whose row names me as approver is directed", () => {
+  const f = facts({ approvals: new Map([["A-1", { id: "A-1", requester: THEM, approver: ME, status: "pending", actionClass: "spend" }]]) });
+  const c = classifyEvent(
+    ev({ family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { requester: THEM, actionClass: "spend", payloadHash: "h" } }),
+  );
+  const v = resolveDirected(c, ME, f);
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "approval", r: "approver" });
+});
+
+test("POSITIVE: the resolution of an approval I requested reaches me (payload-named)", () => {
+  const c = classifyEvent(
+    ev({ family: "approval", kind: "approval.approved", entity_id: "A-2", payload: { requester: ME, approver: THEM } }),
+  );
+  const v = resolveDirected(c, ME, facts());
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "approval", r: "requester" });
+});
+
+test("NEGATIVE: an approval on someone else's desk is not directed", () => {
+  const f = facts({ approvals: new Map([["A-3", { id: "A-3", requester: THEM, approver: "M-boss", status: "pending" }]]) });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-3", payload: { requester: THEM } }));
+  const v = resolveDirected(c, ME, f);
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "not_my_approval");
+});
+
+// ---------------------------------------------------------------------------
+// handoff
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: a handoff offered to me is directed; one between others is not", () => {
+  const mine = classifyEvent(
+    ev({ family: "handoff", kind: "handoff.offered", entity_id: "R-1", payload: { itemId: "T-1", from: THEM, to: ME, intent: "review" } }),
+  );
+  const v = resolveDirected(mine, ME, facts());
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "handoff", r: "direct" });
+
+  const theirs = classifyEvent(
+    ev({ family: "handoff", kind: "handoff.offered", entity_id: "R-2", payload: { itemId: "T-2", from: THEM, to: "M-boss" } }),
+  );
+  assert.equal(resolveDirected(theirs, ME, facts()).directed, false);
+});
+
+test("POSITIVE: my own offer being accepted comes back as reason requester", () => {
+  const c = classifyEvent(
+    ev({ family: "handoff", kind: "handoff.accepted", actor: THEM, entity_id: "R-3", payload: { itemId: "T-3", from: ME, to: THEM } }),
+  );
+  assert.equal(resolveDirected(c, ME, facts()).reason, "requester");
+});
+
+// ---------------------------------------------------------------------------
+// email
+// ---------------------------------------------------------------------------
+
+test("POSITIVE: inbound email routed to my mailbox is directed (payload names the seat)", () => {
+  const c = classifyEvent(
+    ev({ family: "email", kind: "received", actor: "system", entity_id: "EM-1", payload: { emailMessageId: "EM-1", threadId: "ET-1", mailboxId: "MB-1", memberId: ME, autoSubmitted: false } }),
+  );
+  const v = resolveDirected(c, ME, facts(), { enabled: { email: true } });
+  assert.deepEqual({ s: v.surface, r: v.reason }, { s: "email", r: "direct" });
+});
+
+test("NEGATIVE: another seat's mail, unrouted mail, and auto-submitted mail are all refused", () => {
+  const other = classifyEvent(
+    ev({ family: "email", kind: "received", entity_id: "EM-2", payload: { memberId: THEM, threadId: "ET-2" } }),
+  );
+  assert.equal(resolveDirected(other, ME, facts(), { enabled: { email: true } }).directed, false);
+
+  const unrouted = classifyEvent(
+    ev({ family: "email", kind: "received", entity_id: "EM-3", payload: { memberId: null, unrouted: true } }),
+  );
+  assert.equal(unrouted, null, "unrouted mail belongs to nobody");
+
+  const auto = classifyEvent(
+    ev({ family: "email", kind: "received", entity_id: "EM-4", payload: { memberId: ME, autoSubmitted: true } }),
+  );
+  assert.equal(auto, null, "vacation autoreplies are not inbound work");
+});
+
+test("email is OFF by default, so the default enable map refuses it", () => {
+  const c = classifyEvent(
+    ev({ family: "email", kind: "received", entity_id: "EM-5", payload: { memberId: ME, threadId: "ET-5" } }),
+  );
+  const v = resolveDirected(c, ME, facts(), { enabled: { email: false } });
+  assert.equal(v.directed, false);
+  assert.equal(v.reason, "surface_disabled");
+});
+
+// ---------------------------------------------------------------------------
+// families a daemon must NOT be woken for
+// ---------------------------------------------------------------------------
+
+test("noise families produce no candidate at all", () => {
+  for (const family of ["presence", "cost", "registry", "member", "branding", "subagent"]) {
+    assert.equal(classifyEvent(ev({ family, kind: "beat", payload: { actor: THEM } })), null, family);
+  }
+});
+
+test("classifyEvent never throws on malformed rows", () => {
+  for (const bad of [null, undefined, 42, "x", {}, { family: "board" }, { family: "messaging", kind: "send", payload: null }]) {
+    assert.doesNotThrow(() => classifyEvent(bad));
+  }
+});
+
+// ---------------------------------------------------------------------------
+// matchesMyName
+// ---------------------------------------------------------------------------
+
+test("matchesMyName respects word boundaries and the @ prefix", () => {
+  const f = { myNames: ["Isla", "Isla Roselli"] };
+  assert.equal(matchesMyName(f, "Isla, can you look?"), true);
+  assert.equal(matchesMyName(f, "@isla please"), true);
+  assert.equal(matchesMyName(f, "islands are nice"), false);
+  assert.equal(matchesMyName(f, "the island"), false);
+  assert.equal(matchesMyName({ myNames: [] }, "Isla"), false, "no names configured → never matches");
+});