@cohortapp/agent-sdk 2.3.2 → 2.4.0

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

@@ -0,0 +1,287 @@
+/**
+ * project.test.mjs — the projection onto the EXISTING MessageEvent contract.
+ *
+ * The design promise is "the inbox pipeline needs no change", so these tests do
+ * not stop at the MessageEvent: they push it through the real
+ * `lib/channels/inbox-item.eventToInboxItem` and assert the flat item the daemon
+ * actually reads. In particular:
+ *
+ *   - the per-surface `kind` SURVIVES `normalizeKind` (it would be silently
+ *     rewritten to "message" if `contract.EVENT_KINDS` had not been extended),
+ *   - the inbox `id` is stable across an at-least-once replay (it is the dedup
+ *     key, and the cursor is advanced only after the write), and
+ *   - the DM/call projections stay compatible with what `lib/org/messaging`
+ *     produces today, so switching the tail on cannot re-deliver or re-shape the
+ *     inbound that already works.
+ *
+ * Run: node --test lib/org/inbound/project.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { toMessageEvent, inboxIdFor, messageIdFor, scopeFor } from "./project.mjs";
+import { classifyEvent } from "./directedness.mjs";
+import { SURFACES, SURFACE_EVENT_KINDS, resolveEnabledSurfaces, parseSurfaceEnv, defaultEnabledSurfaces } from "./surfaces.mjs";
+import { eventToInboxItem } from "../../channels/inbox-item.mjs";
+import { EVENT_KINDS, normalizeKind } from "../../channels/contract.mjs";
+
+const ME = "M-me";
+const THEM = "M-them";
+
+function ev(over) {
+  return { seq: 42, at: "2026-08-11T09:00:00.000Z", actor: THEM, ...over };
+}
+
+function project(candidate, surface, reason, hydrated, facts = {}) {
+  return toMessageEvent({
+    candidate,
+    verdict: { surface, reason, directed: true },
+    hydrated: { ok: true, ...hydrated },
+    me: ME,
+    facts,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// contract drift — the whole routing hint depends on this
+// ---------------------------------------------------------------------------
+
+test("every surface kind is a REGISTERED EventKind (else normalizeKind eats it)", () => {
+  for (const kind of SURFACE_EVENT_KINDS) {
+    assert.ok(EVENT_KINDS.includes(kind), `contract.EVENT_KINDS is missing "${kind}"`);
+    assert.equal(normalizeKind(kind), kind, `"${kind}" would be rewritten to "message"`);
+  }
+});
+
+test("the five original chat kinds are untouched", () => {
+  for (const kind of ["message", "reaction", "channel_cc", "voice_note", "call"]) {
+    assert.ok(EVENT_KINDS.includes(kind));
+  }
+});
+
+test("email is the one surface OFF by default (the orgmail adapter already polls it)", () => {
+  const d = defaultEnabledSurfaces();
+  assert.equal(d.email, false);
+  for (const [name, on] of Object.entries(d)) {
+    if (name !== "email") assert.equal(on, true, `${name} should default on`);
+  }
+});
+
+test("surface overrides: array = exact set, object = delta, env grammar", () => {
+  assert.deepEqual(resolveEnabledSurfaces(["mention"]).enabled.mention, true);
+  assert.deepEqual(resolveEnabledSurfaces(["mention"]).enabled.dm, false);
+  assert.deepEqual(resolveEnabledSurfaces({ email: true }).enabled.email, true);
+  assert.deepEqual(resolveEnabledSurfaces({ email: true }).enabled.dm, true, "a delta keeps the rest");
+  assert.deepEqual(resolveEnabledSurfaces({ nope: true }).unknown, ["nope"]);
+
+  assert.equal(parseSurfaceEnv(""), undefined);
+  assert.equal(parseSurfaceEnv("default"), undefined);
+  assert.deepEqual(parseSurfaceEnv("mention,thread_reply"), ["mention", "thread_reply"]);
+  assert.deepEqual(parseSurfaceEnv("+email,-thread_reply"), { email: true, thread_reply: false });
+  assert.equal(parseSurfaceEnv("all").email, true);
+  assert.equal(parseSurfaceEnv("none").dm, false);
+});
+
+// ---------------------------------------------------------------------------
+// per-surface projection → real inbox item
+// ---------------------------------------------------------------------------
+
+test("an @mention projects to kind:'mention' and survives eventToInboxItem", () => {
+  const c = classifyEvent(
+    ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C-pub", channelKind: "PUBLIC", mentionCount: 1 } }),
+  );
+  const facts = { channels: new Map([["C-pub", { id: "C-pub", kind: "PUBLIC", name: "General" }]]) };
+  const mev = project(c, "mention", "mention", {
+    text: "@Isla can you look?",
+    from: { id: THEM, name: "Casey" },
+    channelId: "C-pub",
+    channelLabel: "General",
+  }, facts);
+
+  assert.equal(mev.kind, "mention");
+  assert.equal(mev.subject, "Cohort @mention");
+  assert.equal(mev.priority_signals.mentions_agent, true);
+  assert.equal(mev.is_private, false, "a PUBLIC room is a positive public assertion");
+  assert.equal(mev.raw_ref, "cohort:mention:m1:42");
+
+  const item = eventToInboxItem(mev);
+  assert.equal(item.kind, "mention", "the routing hint must reach the daemon");
+  assert.equal(item.service, "cohort");
+  assert.equal(item.channel, "General");
+  assert.equal(item.content, "@Isla can you look?");
+  assert.equal(item.sender, "Casey");
+  assert.equal(item.is_private, false);
+});
+
+test("a board assignment projects to kind:'task_assigned' with the task as the thread", () => {
+  const c = classifyEvent(ev({ family: "board", kind: "item.assigned", entity_id: "T-1", payload: { actor: THEM, assignee: ME } }));
+  const mev = project(c, "task_assigned", "assignee", {
+    text: 'A board item was assigned to you — "Ship the thing"',
+    subjectDetail: "Ship the thing",
+    threadId: "T-1",
+    from: { id: THEM, name: "Casey" },
+    channelLabel: "task/Ship the thing",
+  });
+
+  assert.equal(mev.kind, "task_assigned");
+  assert.equal(mev.subject, "Cohort task assigned: Ship the thing");
+  assert.equal(mev.thread_id, "T-1");
+  assert.equal(mev.is_private, true, "a non-channel org surface is never public");
+  const item = eventToInboxItem(mev);
+  assert.equal(item.kind, "task_assigned");
+  assert.equal(item.thread_id, "T-1");
+  assert.equal(item.id, "cohort-task_assigned-42");
+});
+
+test("each remaining surface projects to its own kind", () => {
+  const cases = [
+    ["thread_reply", classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m2", payload: { actor: THEM, channelId: "C", channelKind: "PUBLIC", threaded: true } }))],
+    ["task_comment", classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-2", payload: { actor: THEM } }))],
+    ["file_comment", classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc1", payload: { fileKey: "k", channelId: "C" } }))],
+    ["doc_comment", classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-1", payload: { name: "Spec" } }))],
+    ["approval", classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { requester: THEM } }))],
+    ["decision", classifyEvent(ev({ family: "decision", kind: "decision.comment", entity_id: "D-1", payload: { authorId: THEM } }))],
+    ["escalation", classifyEvent(ev({ family: "escalation", kind: "escalation.raised", entity_id: "E-1", payload: { actor: THEM } }))],
+    ["handoff", classifyEvent(ev({ family: "handoff", kind: "handoff.offered", entity_id: "R-1", payload: { from: THEM, to: ME } }))],
+    ["email", classifyEvent(ev({ family: "email", kind: "received", entity_id: "EM-1", payload: { memberId: ME, threadId: "ET-1" } }))],
+  ];
+  for (const [surface, cand] of cases) {
+    const mev = project(cand, surface, "direct", { text: "something happened", from: { id: THEM, name: "Casey" } });
+    assert.ok(mev, `${surface} must project`);
+    assert.equal(mev.kind, SURFACES[surface].kind, surface);
+    const item = eventToInboxItem(mev);
+    assert.equal(item.kind, SURFACES[surface].kind, `${surface} kind must survive serialisation`);
+    assert.equal(item.service, "cohort");
+    assert.ok(item.content, `${surface} must carry a body`);
+  }
+  // doc_comment and file_comment deliberately share one kind: they are the same
+  // thing to a classifier ("someone commented on a file of mine").
+  assert.equal(SURFACES.doc_comment.kind, SURFACES.file_comment.kind);
+});
+
+// ---------------------------------------------------------------------------
+// the legacy DM / call shape must not move
+// ---------------------------------------------------------------------------
+
+test("a DM projects to the SAME kind/id/subject the current pullInbound produces", () => {
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m9", payload: { actor: THEM, channelId: "C-dm", channelKind: "DM" } }));
+  const facts = { channels: new Map([["C-dm", { id: "C-dm", kind: "DM", name: "them" }]]) };
+  const mev = project(c, "dm", "dm", { text: "ping", from: { id: THEM, name: "Casey" }, channelId: "C-dm", channelLabel: "them" }, facts);
+
+  assert.equal(mev.kind, "message", "an existing DM must NOT change kind");
+  assert.equal(mev.id, "cohort-m9", "the dedup id must not move");
+  assert.equal(mev.subject, "Cohort message");
+  assert.equal(mev.channel, "cohort");
+  assert.equal(mev.source.userScope, "dm");
+  assert.equal(mev.is_dm, true);
+
+  const item = eventToInboxItem(mev);
+  assert.equal("kind" in item, false, "kind 'message' stays omitted, as it is today");
+  assert.equal(item.id, "cohort-m9");
+});
+
+test("a call keeps kind:'call' and the call id", () => {
+  const c = classifyEvent(ev({ family: "calling", kind: "call.started", entity_id: "call-1", payload: { actor: THEM, callId: "call-1", channelId: "C-dm", topic: "sync" } }));
+  const mev = project(c, "call", "channel", { text: "Call invite: sync", subjectDetail: "sync", threadId: "call-1", from: { id: THEM, name: "Casey" }, channelId: "C-dm" });
+  assert.equal(mev.kind, "call");
+  assert.equal(mev.id, "cohort-call-1");
+  assert.equal(eventToInboxItem(mev).kind, "call");
+});
+
+// ---------------------------------------------------------------------------
+// dedup ids + replay stability
+// ---------------------------------------------------------------------------
+
+test("the inbox id is STABLE across a replay of the same ledger row", () => {
+  const mk = () => classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }));
+  const a = project(mk(), "task_comment", "assignee", { text: "a" });
+  const b = project(mk(), "task_comment", "assignee", { text: "a" });
+  assert.equal(a.id, b.id, "an at-least-once re-pull must dedup, not double-deliver");
+});
+
+test("two comments on the SAME task get different ids", () => {
+  const one = classifyEvent({ seq: 10, family: "board", kind: "item.commented", entity_id: "T-1", actor: THEM, payload: { actor: THEM } });
+  const two = classifyEvent({ seq: 11, family: "board", kind: "item.commented", entity_id: "T-1", actor: THEM, payload: { actor: THEM } });
+  assert.notEqual(
+    project(one, "task_comment", "assignee", { text: "a" }).id,
+    project(two, "task_comment", "assignee", { text: "b" }).id,
+  );
+});
+
+test("id/messageId helpers are explicit about their two regimes", () => {
+  const msg = { family: "messaging", ids: { messageId: "m1" }, entityId: "m1", seq: 5 };
+  assert.equal(messageIdFor(msg, {}), "m1");
+  assert.equal(inboxIdFor(msg, { surface: "dm" }, "m1", "5"), "cohort-m1");
+  const task = { family: "board", ids: { taskId: "T-1" }, entityId: "T-1", seq: 5 };
+  assert.equal(messageIdFor(task, {}), "5");
+  assert.equal(inboxIdFor(task, { surface: "task_comment" }, "5", "5"), "cohort-task_comment-5");
+});
+
+// ---------------------------------------------------------------------------
+// signals + refusals
+// ---------------------------------------------------------------------------
+
+test("mentions_agent is only true for a real direct address", () => {
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }));
+  assert.equal(project(c, "task_comment", "assignee", { text: "x" }).priority_signals.mentions_agent, false);
+  assert.equal(project(c, "task_comment", "direct", { text: "x" }).priority_signals.mentions_agent, true);
+});
+
+test("urgency and deadline signals come off the hydrated body, and blocks are urgent", () => {
+  const c = classifyEvent(ev({ family: "board", kind: "board.blocked", entity_id: "T-1", payload: { actor: THEM, reason: "waiting" } }));
+  const mev = project(c, "task_comment", "assignee", { text: "this is blocked, need it by Friday" });
+  assert.equal(mev.priority_signals.tagged_urgent, true);
+  assert.equal(mev.priority_signals.contains_deadline, true);
+});
+
+test("projection REFUSES an unhydrated, bodyless or surfaceless item", () => {
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }));
+  assert.equal(toMessageEvent({ candidate: c, verdict: { surface: "task_comment" }, hydrated: { ok: false }, me: ME }), null);
+  assert.equal(project(c, "task_comment", "assignee", { text: "   " }), null);
+  assert.equal(toMessageEvent({ candidate: c, verdict: { surface: "nope" }, hydrated: { ok: true, text: "x" }, me: ME }), null);
+  assert.equal(toMessageEvent({}), null);
+});
+
+test("is_private is stamped only when the room class is actually known", () => {
+  const c = classifyEvent(ev({ family: "messaging", kind: "send", entity_id: "m1", payload: { actor: THEM, channelId: "C", channelKind: "PRIVATE" } }));
+  assert.equal(project(c, "mention", "mention", { text: "x", channelId: "C" }).is_private, true);
+
+  const noKind = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc", payload: { fileKey: "k", channelId: "C-unknown" } }));
+  const mev = project(noKind, "file_comment", "channel", { text: "x", channelId: "C-unknown" });
+  assert.equal("is_private" in mev, false, "an unknown room class must not forge a confidentiality assertion");
+});
+
+test("channel_id is ONLY ever a real channel id — never an entity id in disguise", () => {
+  // `responder.sendCohortReply` does `messaging.send({channel: item.channel_id})`.
+  // A task id here would post to a non-channel and 400, so a room-less surface
+  // must leave it blank and be routed by `kind` + `raw_ref` instead.
+  const roomless = [
+    ["task_comment", classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-1", payload: { actor: THEM } }))],
+    ["decision", classifyEvent(ev({ family: "decision", kind: "decision.comment", entity_id: "D-1", payload: { authorId: THEM } }))],
+    ["approval", classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { requester: THEM } }))],
+    ["doc_comment", classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-1", payload: { name: "Spec" } }))],
+    ["handoff", classifyEvent(ev({ family: "handoff", kind: "handoff.offered", entity_id: "R-1", payload: { from: THEM, to: ME } }))],
+  ];
+  for (const [surface, cand] of roomless) {
+    const mev = project(cand, surface, "direct", { text: "x", threadId: "X-1" });
+    assert.equal(mev.channel_id, "", `${surface} must not fake a channel id`);
+    assert.equal(eventToInboxItem(mev).channel_id, "", surface);
+    // The routing information is still there, on fields the converter keeps.
+    assert.match(eventToInboxItem(mev).raw_ref, new RegExp(`^cohort:${surface}:`));
+    assert.ok(eventToInboxItem(mev).thread_id, `${surface} must carry a reply anchor`);
+  }
+
+  // A board item that DOES live in a channel keeps it, so a reply can go there.
+  const inChannel = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-2", payload: { actor: THEM, channelId: "C-eng" } }));
+  assert.equal(project(inChannel, "task_comment", "assignee", { text: "x", channelId: "C-eng" }).channel_id, "C-eng");
+});
+
+test("scopeFor maps room class to the daemon's audience vocabulary", () => {
+  assert.equal(scopeFor("dm", "DM", "channel"), "dm");
+  assert.equal(scopeFor("dm", "GROUP_DM", "channel"), "group");
+  assert.equal(scopeFor("mention", "PUBLIC", "channel"), "channel");
+  assert.equal(scopeFor("approval", "", "dm"), "dm");
+});

package/lib/org/inbound/surfaces.mjs

@@ -0,0 +1,257 @@
+/**
+ * lib/org/inbound/surfaces.mjs — the inbound SURFACE vocabulary.
+ *
+ * Today `pullInbound` tails two families (`messaging`, `calling`) and recognises
+ * exactly two things: a message in a private room I belong to, and a call in one
+ * of my rooms. hq's own in-process responder (`src/server/llm-responder/`) reacts
+ * to eleven inbound triggers, and since hq commit 4d762d30 it STOPS answering for
+ * any member whose daemon has beaten inside 100 s. The net effect for a live SDK
+ * agent is that an @mention in a space is answered by nobody: hq stands down and
+ * the SDK never sees it.
+ *
+ * This table is the parity target expressed as data. Each SURFACE is:
+ *
+ *   - `topic`   the coarse bucket (mirrors hq `agent-stream/relevance.ts` Topic),
+ *   - `kind`    the MessageEvent `kind` written onto the inbox item, so the
+ *               daemon classifier can route WITHOUT parsing prose,
+ *   - `subject` the human-readable inbox subject prefix,
+ *   - `scope`   the `source.userScope` the projection stamps,
+ *   - `default` whether the surface is tailed unless the operator says otherwise.
+ *
+ * Adding a surface is a data edit here plus a `classifyEvent` branch in
+ * `directedness.mjs` — the pull loop, hydration dispatch and projection are all
+ * table-driven off this module.
+ *
+ * Pure data. No IO.
+ *
+ * @module lib/org/inbound/surfaces
+ */
+
+"use strict";
+
+/**
+ * WHY `email` DEFAULTS OFF. The org-mail channel adapter
+ * (lib/channels/orgmail/adapter.mjs) ALREADY polls `email.inbox` every 45 s and
+ * writes its own inbox items under `state/inbox/orgmail/`. Tailing the `email`
+ * family here as well would deliver every inbound mail twice, and the two items
+ * would race for the same thread lease. Enable this surface only when the
+ * orgmail adapter is off (`config/orgmail.yaml` absent) — see README of this
+ * directory / the wiring notes.
+ */
+export const SURFACES = Object.freeze({
+  /** A message in a DM / group-DM / huddle I belong to. Byte-compatible with today. */
+  dm: Object.freeze({
+    topic: "message",
+    kind: "message",
+    subject: "Cohort message",
+    scope: "dm",
+    default: true,
+  }),
+  /** An @mention of me in a public/private space. THE headline gap. */
+  mention: Object.freeze({
+    topic: "message",
+    kind: "mention",
+    subject: "Cohort @mention",
+    scope: "channel",
+    default: true,
+  }),
+  /** A reply in a thread I have spoken in / been named in. */
+  thread_reply: Object.freeze({
+    topic: "message",
+    kind: "thread_reply",
+    subject: "Cohort thread reply",
+    scope: "channel",
+    default: true,
+  }),
+  /** A call started/invited in one of my rooms. Byte-compatible with today. */
+  call: Object.freeze({
+    topic: "call",
+    kind: "call",
+    subject: "Cohort call invite",
+    scope: "channel",
+    default: true,
+  }),
+  /** A board item assigned to me (or claimed/completed on my behalf). */
+  task_assigned: Object.freeze({
+    topic: "task",
+    kind: "task_assigned",
+    subject: "Cohort task assigned",
+    scope: "channel",
+    default: true,
+  }),
+  /** A comment / block / move on a board item I own or review. */
+  task_comment: Object.freeze({
+    topic: "task",
+    kind: "task_comment",
+    subject: "Cohort task update",
+    scope: "channel",
+    default: true,
+  }),
+  /** A comment on a chat-attached file in one of my rooms (family `file`). */
+  file_comment: Object.freeze({
+    topic: "file",
+    kind: "file_comment",
+    subject: "Cohort file comment",
+    scope: "channel",
+    default: true,
+  }),
+  /** A comment / suggestion on a workspace doc I own or am shared on (family `files`). */
+  doc_comment: Object.freeze({
+    topic: "file",
+    kind: "file_comment",
+    subject: "Cohort document comment",
+    scope: "channel",
+    default: true,
+  }),
+  /** An approval on my desk, or the outcome of one I requested. */
+  approval: Object.freeze({
+    topic: "approval",
+    kind: "approval",
+    subject: "Cohort approval",
+    scope: "channel",
+    default: true,
+  }),
+  /** A decision I proposed / commented on / must sign. */
+  decision: Object.freeze({
+    topic: "decision",
+    kind: "decision",
+    subject: "Cohort decision",
+    scope: "channel",
+    default: true,
+  }),
+  /** An escalation raised on my task / in my room / waiting on me. */
+  escalation: Object.freeze({
+    topic: "escalation",
+    kind: "escalation",
+    subject: "Cohort escalation",
+    scope: "channel",
+    default: true,
+  }),
+  /** A delegation offered to me, or one I offered being accepted/declined. */
+  handoff: Object.freeze({
+    topic: "handoff",
+    kind: "handoff",
+    subject: "Cohort handoff",
+    scope: "channel",
+    default: true,
+  }),
+  /** An inbound email routed to my mailbox. OFF by default — see note above. */
+  email: Object.freeze({
+    topic: "email",
+    kind: "email",
+    subject: "Cohort email",
+    scope: "dm",
+    default: false,
+  }),
+});
+
+/** Every surface name, sorted for determinism. */
+export const SURFACE_NAMES = Object.freeze(Object.keys(SURFACES).sort());
+
+/**
+ * The MessageEvent `kind` values these surfaces introduce, beyond the five the
+ * channel contract already ships. `lib/channels/contract.mjs` must list them in
+ * EVENT_KINDS or `eventToInboxItem` will normalise them all back to "message"
+ * and the classifier loses the routing hint. Exported so a test can assert the
+ * two lists have not drifted.
+ */
+export const SURFACE_EVENT_KINDS = Object.freeze(
+  Array.from(new Set(Object.values(SURFACES).map((s) => s.kind))).sort(),
+);
+
+/** The default enable map: `{ surfaceName: boolean }`. */
+export function defaultEnabledSurfaces() {
+  const out = {};
+  for (const [name, def] of Object.entries(SURFACES)) out[name] = def.default;
+  return out;
+}
+
+/**
+ * Resolve the effective enable map from an override.
+ *
+ * Accepts `undefined` (all defaults), an array of surface names (exactly those
+ * on, everything else off), or a partial `{name: boolean}` map merged over the
+ * defaults. Unknown names are IGNORED rather than throwing — a config typo must
+ * not take the inbound loop down (fail-open house rule); the caller gets the
+ * dropped names back so it can log them.
+ *
+ * @param {string[]|Record<string,boolean>|undefined|null} override
+ * @returns {{enabled: Record<string,boolean>, unknown: string[]}}
+ */
+export function resolveEnabledSurfaces(override) {
+  const enabled = defaultEnabledSurfaces();
+  const unknown = [];
+  if (override == null) return { enabled, unknown };
+
+  if (Array.isArray(override)) {
+    for (const key of Object.keys(enabled)) enabled[key] = false;
+    for (const name of override) {
+      const k = String(name);
+      if (Object.prototype.hasOwnProperty.call(enabled, k)) enabled[k] = true;
+      else unknown.push(k);
+    }
+    return { enabled, unknown };
+  }
+
+  if (typeof override === "object") {
+    for (const [name, on] of Object.entries(override)) {
+      if (Object.prototype.hasOwnProperty.call(enabled, name)) enabled[name] = !!on;
+      else unknown.push(String(name));
+    }
+    return { enabled, unknown };
+  }
+
+  return { enabled, unknown };
+}
+
+/**
+ * Parse the `COHORT_INBOUND_SURFACES` env override.
+ *
+ * Grammar (comma separated, whitespace tolerant):
+ *   "all"                     every surface on
+ *   "default"                 the defaults (same as unset)
+ *   "mention,thread_reply"    exactly these on, everything else off
+ *   "+email"                  the defaults PLUS email
+ *   "-thread_reply"           the defaults MINUS thread_reply
+ * A list may mix `+`/`-` entries, in which case it is treated as a delta over
+ * the defaults; a list with no sign prefixes is treated as an exact set.
+ *
+ * @param {string|undefined|null} raw
+ * @returns {string[]|Record<string,boolean>|undefined} an override for
+ *   {@link resolveEnabledSurfaces}, or undefined for "use the defaults".
+ */
+export function parseSurfaceEnv(raw) {
+  const s = typeof raw === "string" ? raw.trim() : "";
+  if (!s) return undefined;
+  const lower = s.toLowerCase();
+  if (lower === "default" || lower === "defaults") return undefined;
+  if (lower === "all") {
+    const all = {};
+    for (const name of SURFACE_NAMES) all[name] = true;
+    return all;
+  }
+  if (lower === "none" || lower === "off") {
+    const none = {};
+    for (const name of SURFACE_NAMES) none[name] = false;
+    return none;
+  }
+  const parts = s.split(",").map((p) => p.trim()).filter(Boolean);
+  const signed = parts.some((p) => p.startsWith("+") || p.startsWith("-"));
+  if (!signed) return parts;
+  const delta = {};
+  for (const p of parts) {
+    if (p.startsWith("+")) delta[p.slice(1)] = true;
+    else if (p.startsWith("-")) delta[p.slice(1)] = false;
+    else delta[p] = true;
+  }
+  return delta;
+}
+
+export default {
+  SURFACES,
+  SURFACE_NAMES,
+  SURFACE_EVENT_KINDS,
+  defaultEnabledSurfaces,
+  resolveEnabledSurfaces,
+  parseSurfaceEnv,
+};

package/lib/org/knowledge.mjs

@@ -377,7 +377,16 @@ export async function listMeetings(opts = {}) {
 // internals (pure shaping)
 // ---------------------------------------------------------------------------
 
-/** Coerce a fact arg (string text or fact object) + opts into the wire params. */
+/**
+ * Coerce a fact arg (string text or fact object) + opts into the wire params.
+ *
+ * `kind` / `participants` / `links` / `refs` are written FLAT here and folded into
+ * hq's `metadata` container by the wire contract in `client.call()`
+ * (lib/org/param-contract#PARAM_CONTRACT["knowledge.append"].fold) — hq's handler
+ * persists enrichment only inside `metadata`, so flat keys were silently dropped
+ * on every append. Keep them flat here: the contract is the one place that knows
+ * hq's shape.
+ */
 function factToParams(fact, opts = {}) {
   const base = typeof fact === "string" ? { text: fact } : (fact && typeof fact === "object" ? { ...fact } : {});
   // Pull through the structured options without letting opts plumbing leak.

package/lib/org/knowledge.test.mjs

@@ -81,7 +81,9 @@ test("remember(string): appends an episode (the sole shared-write primitive)", a
   assert.equal(f.calls[0].url, `${BASE}/api/v1/knowledge.append`);
   assert.equal(f.calls[0].method, "POST");
   assert.equal(f.calls[0].headers.authorization, "Bearer tok");
-  assert.deepEqual(f.calls[0].body, { text: "we closed the Q3 deal", group: "org" });
+  // hq's knowledge.append reads `body` (with `text` accepted as an alias); the
+  // wire contract adds the canonical name and keeps the legacy one alongside.
+  assert.deepEqual(f.calls[0].body, { text: "we closed the Q3 deal", body: "we closed the Q3 deal", group: "org" });
 });
 
 test("remember(fact object): pulls through opts (kind/participants/provenance), normalises group", async () => {
@@ -90,11 +92,16 @@ test("remember(fact object): pulls through opts (kind/participants/provenance),
     { text: "intro call notes" },
     { cfg: CFG, group: { kind: "unit", id: "sales" }, kind: "note", participants: ["a", "b"], provenance: { src: "call" }, fetchImpl: f },
   );
+  // Enrichment hq only persists inside `metadata` is FOLDED there by the wire
+  // contract — flat `kind`/`participants`/`links`/`refs` were silently dropped by
+  // the server on every append before this.
   assert.deepEqual(f.calls[0].body, {
     text: "intro call notes",
+    body: "intro call notes",
     kind: "note",
     participants: ["a", "b"],
     provenance: { src: "call" },
+    metadata: { kind: "note", participants: ["a", "b"] },
     group: "unit:sales",
   });
 });

package/lib/org/leases.mjs

@@ -201,11 +201,16 @@ export async function claimLease(scope, resourceId, opts = {}) {
   }
   const c = resolveClient(opts);
   const ms = Number.isFinite(opts.failOpenTimeoutMs) ? opts.failOpenTimeoutMs : DEFAULT_FAIL_OPEN_MS;
+  // WIRE CONTRACT (hq `methods/lease/claim.ts`): the holder is the AUTHENTICATED
+  // actor — hq never reads a client-supplied `holder`, and the only token field
+  // it models is `tokenHash`. `holder` is kept on the wire (harmless; hq's schema
+  // is not strict) but is documented as not-read in lib/org/param-contract.
   const params = {
     scope,
     resourceId,
     holder: opts.holder || undefined,
     ttlMs: Number.isFinite(opts.ttlMs) ? opts.ttlMs : undefined,
+    ...(opts.tokenHash ? { tokenHash: String(opts.tokenHash) } : {}),
   };
   const frame = await withTimeout(
     Promise.resolve(c.leaseClaim(params, rpcOpts(opts))),

package/lib/org/mesh.mjs

@@ -449,13 +449,28 @@ export async function connectOrgMesh(o = {}) {
     if (entry && entry.id) {
       // Fetch THIS seat's granted tools (SP5); falls back to workspace-wide when absent.
       ctx.agentMemberId = entry.id;
-      await client.register(entry, {
+      // The rich self-entry is projected onto hq's `.strict()` registerSchema by
+      // the wire contract inside client.call (param-contract#toRegisterParams);
+      // passing it raw used to 400 on every boot.
+      const frame = await client.register(entry, {
         base: conn.base,
         token: conn.token,
         idempotencyKey: `registry.register:${entry.id}`,
         fetchImpl: o.fetchImpl,
       });
-      logInfo(`registered ${entry.id} with the org mesh`);
+      // NEVER claim success we did not get. `register` fails OPEN (it returns an
+      // error frame rather than throwing), and this line used to log "registered
+      // …" unconditionally — so a rejected registration looked healthy on every
+      // boot while the agent was absent from the directory.
+      if (frame && frame.ok) {
+        logInfo(`registered ${entry.id} with the org mesh`);
+      } else {
+        const err = (frame && frame.error) || {};
+        logWarn(
+          `registration REJECTED for ${entry.id} (${err.code || "unknown"}: ${err.message || "no detail"}) ` +
+            `— this agent is NOT in the org directory; presence-beat will retry`,
+        );
+      }
     }
   } catch (err) {
     logWarn(`registration failed (${err && err.message}) — continuing; presence-beat will retry`);