@cohortapp/agent-sdk 2.16.0 → 2.18.4

package/lib/org/inbound/broadcast.mjs

@@ -0,0 +1,289 @@
+/**
+ * lib/org/inbound/broadcast.mjs — "did a human just address EVERYONE?"
+ *
+ * PURE. No IO, no clock, no config. The one place the collective-address
+ * vocabulary lives on this side of the org.
+ *
+ * ── WHY THIS EXISTS ──
+ * On 2026-09-21 a human posted in #general: "Can everyone give me an update on
+ * what they're doing right now (across sessions on your machines)?". Thirteen
+ * agents were members. Zero replied. Not a regression — a standing gap: the
+ * addressing layer knew DMs, @mentions, threads and prose names, and had NO
+ * concept of a message addressed to the whole room. A space post with
+ * `mentionCount: 0` was dropped structurally (`no_mentions_not_threaded`)
+ * before its body was ever read, on every seat, including the ones that were
+ * up and healthy.
+ *
+ * ── THE RULE (implemented by `resolveMessaging` in directedness.mjs) ──
+ * A space post is a BROADCAST when ALL of:
+ *   1. the author is HUMAN — agents never broadcast to each other; a peer's
+ *      "everyone please review" is ambient traffic, not a roll-call;
+ *   2. it is in a public/private SPACE this seat is a member of — never a DM
+ *      (a DM is already addressed by construction and stays a DM even when it
+ *      says "everyone");
+ *   3. it is not threaded — a thread reply keeps the existing thread rule;
+ *   4. the body matches one of {@link BROADCAST_PATTERNS}.
+ *
+ * ── THE TWIN ──
+ * hq carries a faithful port of this module at
+ * `src/server/llm-responder/broadcast.ts` for agents WITHOUT a machine (the
+ * LLM_RESPONDER path). The two are separate packages and cannot import each
+ * other, so BOTH pin the same {@link BROADCAST_CORPUS} in their tests. Change
+ * a pattern here and the hq twin's test goes red until it is changed there
+ * too — that is the drift guard, keep the corpus identical on both sides.
+ *
+ * @module lib/org/inbound/broadcast
+ */
+
+"use strict";
+
+/**
+ * The explicit collective addresses, in match order. Case-insensitive, anchored
+ * to word boundaries, so "all" alone, "you" alone, "you all right?" and
+ * "thanks all" do NOT match — only a phrase that unambiguously names the whole
+ * room does. `team,` is only a broadcast when it OPENS the message ("Team, quick
+ * check-in") — mid-sentence "the team" is a noun, not an address.
+ *
+ * Ordered most-common-first; order does not change the verdict, only which
+ * pattern is reported as the match.
+ *
+ * @type {readonly RegExp[]}
+ */
+export const BROADCAST_PATTERNS = Object.freeze([
+  /\beveryone\b/i,
+  /\beverybody\b/i,
+  /\ball of you\b/i,
+  /\beach of you\b/i,
+  /\bthe whole team\b/i,
+  /^\s*team\s*,/i,
+  /(^|[^\w@])@here\b/i,
+  /(^|[^\w@])@channel\b/i,
+  /(^|[^\w@])@all\b/i,
+  /\ball agents\b/i,
+  /\ball colleagues\b/i,
+  /\broll[ -]?call\b/i,
+  /\bsound off\b/i,
+  /\bstatus check\b/i,
+]);
+
+/**
+ * Is this message body an explicit address to the whole room?
+ *
+ * Pure text test — the author/room/thread conditions are the caller's
+ * (`resolveMessaging`); this answers ONLY condition 4.
+ *
+ * @param {unknown} body
+ * @returns {boolean}
+ */
+export function isBroadcast(body) {
+  const text = typeof body === "string" ? body : "";
+  if (!text.trim()) return false;
+  return BROADCAST_PATTERNS.some((re) => re.test(text));
+}
+
+/**
+ * Which pattern matched, as a stable label for a log line / a test. Null when
+ * none did.
+ *
+ * @param {unknown} body
+ * @returns {string|null}
+ */
+export function broadcastMatch(body) {
+  const text = typeof body === "string" ? body : "";
+  if (!text.trim()) return null;
+  for (const re of BROADCAST_PATTERNS) {
+    const m = re.exec(text);
+    if (m) return m[0].trim().toLowerCase();
+  }
+  return null;
+}
+
+/**
+ * THE SHARED CORPUS. Literal strings, pinned by directedness.test.mjs here and
+ * by hq's broadcast.test.ts. `positive` must all be broadcasts; `negative` must
+ * all NOT be. The first positive is the actual message that went unanswered.
+ */
+export const BROADCAST_CORPUS = Object.freeze({
+  positive: Object.freeze([
+    "Can everyone give me an update on what they're doing right now (across sessions on your machines)?",
+    "did everyone see the deck?",
+    "Everybody: standup in 5",
+    "Quick one for all of you — what's blocking you today?",
+    "I'd like each of you to post your top priority",
+    "Thanks to the whole team for the push last night, what's next on your plates?",
+    "Team, quick check-in: what are you on?",
+    "@here who is around?",
+    "@channel status please",
+    "@all please confirm you can see this",
+    "all agents: report your current task",
+    "All colleagues, a quick update from your side please",
+    "roll call",
+    "Roll-call — sound off with what you're working on",
+    "status check: where is everyone at?",
+  ]),
+  negative: Object.freeze([
+    "all good here",
+    "thanks all",
+    "I'll take all three",
+    "you all right?",
+    "pushed the fix, ready for review",
+    "can you look at the deck?",
+    "the team offsite is on Thursday",
+    "email me at ops@all-hands.example",
+    "what is the status of the migration?",
+    "",
+  ]),
+});
+
+// ---------------------------------------------------------------------------
+// Reply shaping — what a roll-call respondent is told
+// ---------------------------------------------------------------------------
+
+/** The MessageEvent / inbox `kind` and the verdict `reason` a broadcast carries. */
+export const BROADCAST_KIND = "broadcast";
+export const BROADCAST_REASON = "collective";
+
+/**
+ * Is this flattened inbox item a roll-call delivery? Reads the two fields the
+ * projection carries across `eventToInboxItem` (`kind`, `direct_reason`), so a
+ * daemon can gate on it without re-parsing prose.
+ *
+ * @param {object} item
+ * @returns {boolean}
+ */
+export function isRollCallItem(item) {
+  if (!item || typeof item !== "object") return false;
+  if (String(item.kind || "") === BROADCAST_KIND) return true;
+  if (String(item.direct_reason || "") === BROADCAST_REASON) return true;
+  const cohort = item.cohort && typeof item.cohort === "object" ? item.cohort : null;
+  return !!cohort && String(cohort.surface || "") === BROADCAST_KIND;
+}
+
+/** Hard ceiling on a roll-call reply, in lines. The prompt says it; the fleet keeps it. */
+export const ROLL_CALL_MAX_LINES = 5;
+
+/**
+ * The reply-shaping block injected into whichever prompt composes the answer —
+ * the daemon's quick-reply responder or a spawned session. One text, both
+ * paths, so a collective answer reads the same however it was produced. The
+ * FACTS the answer is composed from are the current-work block
+ * (lib/session/current-work), which both paths already carry.
+ *
+ * ONE TEXT, THREE INTENTS (`collective.mjs`). The discipline is shared —
+ * answer for yourself, do not speak for anyone else, do not @mention, do not
+ * acknowledge — and exactly one line differs, because exactly one thing
+ * differs:
+ *
+ *   roll-call → report on yourself: what you are doing, queued, blocked.
+ *   work      → say what YOUR slice is and by when. The ask is already a row
+ *               on the board (one per addressee), so the reply is a plan, not
+ *               a status line — and telling the session the row exists is what
+ *               stops it writing "I'll open a task for this".
+ *   ambient   → the room was addressed and nothing was asked. Answer in your
+ *               own lane and do NOT mint work from it, which is the prompt-side
+ *               half of the same guard `HEDGE_PATTERNS` enforces in code.
+ *
+ * Word-for-word hq's `src/server/llm-responder/broadcast.ts`, so a seat
+ * answered by its own daemon and a seat answered by hq read the same in the
+ * room.
+ *
+ * @param {{intent?: string, respondents?: number|null}} [o] `respondents` — how
+ *   many AI members the org has (an upper bound on who else answers; the room
+ *   roster is not visible to a seat). Omitted or non-finite ⇒ "several".
+ * @returns {string}
+ */
+export function collectiveInstructions(o = {}) {
+  const n = Number.isFinite(o.respondents) && o.respondents > 0 ? o.respondents : null;
+  const who = n ? `one of up to ${n} colleagues` : "one of several colleagues";
+  const intent = o.intent || "roll-call";
+  const banner = intent === "roll-call" ? "ROLL-CALL" : "ADDRESSED TO EVERYONE";
+  const framing =
+    intent === "work"
+      ? `A human asked the whole room to do something, not you specifically. You are ${who} who will answer the same message. Every addressed member owns its own slice; nobody answers for the group.`
+      : `A human addressed the whole room, not you specifically. You are ${who} who will answer the same message. Every addressed member answers for itself; nobody answers for the group.`;
+  const content =
+    intent === "work"
+      ? `- This ask is already on the board as YOUR OWN item, so do not open another one. Reply in at most ${ROLL_CALL_MAX_LINES} short lines, about your slice only: what you will do about it, and by when. Facts, not adjectives.`
+      : intent === "ambient"
+        ? `- Nothing was asked of you here, so do not turn it into a task. Reply in at most ${ROLL_CALL_MAX_LINES} short lines, from your own lane only. Facts, not adjectives.`
+        : `- Reply in at most ${ROLL_CALL_MAX_LINES} short lines, about YOURSELF only: what you are doing right now, what is queued, what is blocked. Facts, not adjectives.`;
+  return [
+    `===== ${banner} =====`,
+    framing,
+    content,
+    "- Do NOT summarise, list, guess at or speak for anyone else's status.",
+    "- Do NOT @mention anyone. Do not address other agents. Do not ask the room a question back.",
+    "- Do NOT post an acknowledgement, a holding line or a 'checking now' — say nothing until the answer itself is ready, then post it once.",
+    "- Do not restate the question and do not open with a greeting; the first line is already the answer.",
+    `===== END ${banner} =====`,
+  ].join("\n");
+}
+
+/**
+ * The roll-call arm of {@link collectiveInstructions}, kept as its own export
+ * because it is what every existing call site and test names. Byte-identical to
+ * the text this module has always produced.
+ *
+ * @param {{respondents?: number|null}} [o]
+ * @returns {string}
+ */
+export function rollCallInstructions(o = {}) {
+  return collectiveInstructions({ ...o, intent: "roll-call" });
+}
+
+// WHAT THE SEAT IS DOING is not rendered here. This module briefly carried a
+// `renderSelfActivity` (status by session name, peers by name, handoffs,
+// every board row, the daemon's active sessions) that the quick reply injected
+// NEXT TO lib/session/current-work's block — two accounts of one state, and
+// the one here quoted session names. The single renderer is
+// lib/session/current-work (`currentWorkBlock`, audience- and barrier-scoped);
+// what this one carried that it lacked moved there. Do not add a second.
+
+// ---------------------------------------------------------------------------
+// Rate shaping — 13 replies must not land in the same second
+// ---------------------------------------------------------------------------
+
+/** The jitter window a roll-call reply is spread across, per channel. */
+export const ROLL_CALL_JITTER_MAX_MS = 20_000;
+
+/** FNV-1a 32-bit over a string. Deterministic, dependency-free. */
+function fnv1a(s) {
+  let h = 0x811c9dc5;
+  for (let i = 0; i < s.length; i += 1) {
+    h ^= s.charCodeAt(i);
+    h = Math.imul(h, 0x01000193) >>> 0;
+  }
+  return h >>> 0;
+}
+
+/**
+ * How long THIS seat waits before posting its roll-call answer. Deterministic
+ * per (seat, channel, message): the same seat answering the same roll-call
+ * after a crash waits the same amount, and thirteen seats spread across the
+ * window instead of stacking on the second the event landed. Pure — no
+ * randomness — so a test can pin it.
+ *
+ * @param {{seat?:string, channelId?:string, messageId?:string, maxMs?:number}} o
+ * @returns {number} milliseconds in [0, maxMs)
+ */
+export function rollCallJitterMs(o = {}) {
+  const max = Number.isFinite(o.maxMs) && o.maxMs >= 0 ? o.maxMs : ROLL_CALL_JITTER_MAX_MS;
+  if (max === 0) return 0;
+  const key = `${o.seat || ""}|${o.channelId || ""}|${o.messageId || ""}`;
+  return fnv1a(key) % max;
+}
+
+export default {
+  BROADCAST_PATTERNS,
+  BROADCAST_CORPUS,
+  BROADCAST_KIND,
+  BROADCAST_REASON,
+  ROLL_CALL_MAX_LINES,
+  ROLL_CALL_JITTER_MAX_MS,
+  isBroadcast,
+  broadcastMatch,
+  isRollCallItem,
+  collectiveInstructions,
+  rollCallInstructions,
+  rollCallJitterMs,
+};

package/lib/org/inbound/collective.mjs

@@ -0,0 +1,375 @@
+/**
+ * lib/org/inbound/collective.mjs — a message addressed to EVERYONE: is it work?
+ *
+ * PURE. No IO, no clock, no config. The twin of hq's
+ * `src/server/work/collective.ts`.
+ *
+ * ── THE QUESTION THIS ANSWERS, AND THE ONE IT DOES NOT ──
+ * `broadcast.mjs#isBroadcast` answers ADDRESSING: did a human name the whole
+ * room? This module answers what comes next, and only that: GIVEN that the
+ * room was addressed collectively, is the message a ROLL-CALL (report on
+ * yourself), WORK (go and do a thing), or AMBIENT (neither)?
+ *
+ * It deliberately does NOT re-test the address — `directedness.mjs#
+ * isBroadcastFor` already settled that, and asking twice is how two places
+ * come to disagree about one question.
+ *
+ * ── WHY IT EXISTS ──
+ * 2026-09-21 fixed the first half: "Can everyone give me an update?" drew zero
+ * replies from thirteen members. The half it did not fix: "Everyone, please
+ * review the binder by Friday" drew replies and NO BOARD ROWS, on both planes.
+ * Work addressed to everyone did no work.
+ *
+ * ── THE RULE, IN THE CODE THAT IMPLEMENTS IT ──
+ *
+ * 1. ROLL-CALL AND WORK ARE NOT MUTUALLY EXCLUSIVE TEXT, so they are not
+ *    tested in sequence. "Everyone, please review the binder and give me an
+ *    update when it's done" is BOTH shapes in one sentence, and a first-match
+ *    ladder gets it wrong whichever order it is written in. Instead the
+ *    roll-call phrases are EXCISED from the body and the work gate runs on
+ *    what is left: if the residue still asks for work, it is work; if the work
+ *    reading only ever came from the status phrasing, it is a roll-call. That
+ *    is also what keeps "can everyone give me an UPDATE" from being work —
+ *    `update` is an action verb, and without the excision the plainest
+ *    roll-call in the corpus would open thirteen board rows.
+ *
+ * 2. A HEDGE DEFUSES WORK. "everyone should take a look sometime", "feel free
+ *    to review when you get a chance", "no rush" — a board that mints thirteen
+ *    rows for each of those is a board the owner stops opening within a week.
+ *    A hedge is read BEFORE the verb, so no amount of imperative grammar beats
+ *    "if anyone has a minute".
+ *
+ * 3. THE WORK TEST IS hq's. `asksForWork` / `hasSubstance` below are a VERBATIM
+ *    port of `src/server/work/threshold.ts` — not a second opinion about what
+ *    work looks like. A collective ask and a direct ask are the same ask with a
+ *    different audience.
+ *
+ * ── WHAT THIS FILE MAY AND MAY NOT DECIDE ──
+ * It shapes a PROMPT and routes a FAST PATH. It NEVER decides whether a board
+ * row exists. That judgement stays single-implementation on the server:
+ * `work-ledger.mjs` sends `collective: true` plus the body over `board.track`,
+ * and hq's `assessAskWithAudience` runs its own copy of this classifier. A
+ * daemon that got the verdict wrong here therefore loses a nicely-shaped
+ * prompt, never a row it should not have opened.
+ *
+ * ── THE TWIN ──
+ * Both sides pin {@link COLLECTIVE_CORPUS}, byte-for-byte. Change a pattern
+ * here and hq's `collective.test.ts` goes red until it is changed there too —
+ * the same drift guard BROADCAST_CORPUS already runs for the address.
+ *
+ * @module lib/org/inbound/collective
+ */
+
+"use strict";
+
+// ---------------------------------------------------------------------------
+// VERBATIM PORT of hq src/server/work/threshold.ts. Do not "improve" either
+// copy alone: the corpus below is what holds them together, and the board gate
+// that matters runs hq's copy.
+// ---------------------------------------------------------------------------
+
+/** Shortest ask we will treat as an ask at all. */
+const MIN_SUBSTANCE_CHARS = 12;
+
+/** A chase or a pleasantry — a reaction to work, never a request for it. */
+const NO_SUBSTANCE =
+  /^(?:[\s?!.…]*|\?+|pls|please|ping|bump|any\s+updates?|updates?|status|well\?|and\?|thanks?|thank\s+you|ty|thx|cheers|ok(?:ay)?|kk|got\s+it|sure|nice|great|cool|perfect|lovely|yes|yep|no|nope|nvm|never\s+mind|👍|🙏|🎉)[\s?!.…]*$/i;
+
+/** An explicit "do not action this" prefix, honoured before anything else. */
+const NO_ACTION_PREFIX = /^\s*(?:fyi\b|no\s+action\b|just\s+so\s+you\s+know\b)/i;
+
+/**
+ * Verbs that name WORK. Kept to things that produce an artifact or change the
+ * world — deliberately NOT "explain", "tell", "what", "why", which are answered
+ * in the turn and leave the reply as their own artifact.
+ */
+const ACTION_VERB =
+  "(?:fix|ship|build|write|draft|send|create|make|set\\s+up|update|upgrade|migrate|deploy|" +
+  "investigate|look\\s+into|dig\\s+into|sort\\s+out|figure\\s+out|chase|review|prepare|prep|" +
+  "schedule|book|publish|add|remove|delete|refactor|debug|push|merge|implement|plan|research|" +
+  "analyse|analyze|compile|produce|generate|organise|organize|follow\\s+up|resolve|land|" +
+  "roll\\s+out|audit|clean\\s+up|tidy|rename|document|write\\s+up|pull\\s+together|put\\s+together|" +
+  "sort|handle|action|own|drive|unblock|test|verify|check\\s+into|reconcile)";
+
+/** An imperative: the verb opens a sentence ("fix these issues and push them"). */
+const IMPERATIVE = new RegExp(
+  `(?:^|[.!?;,\\n]\\s*|\\b(?:and|then|also|please|pls|first|next|now)\\s+)` +
+    `(?:(?:also|then|now|and|please|pls|first|next)\\s+){0,2}${ACTION_VERB}\\b`,
+  "i",
+);
+
+/** A polite request wrapper ("could you look into…", "I need you to draft…"). */
+const REQUEST = new RegExp(
+  `\\b(?:can|could|would|will|please|pls|need\\s+(?:you\\s+)?to|needs?\\s+to|want\\s+you\\s+to|` +
+    `like\\s+you\\s+to|should\\s+you|mind)\\b[^.!?\\n]{0,40}?\\b${ACTION_VERB}\\b`,
+  "i",
+);
+
+/**
+ * Does this text ask the agent to DO something (as opposed to answer something)?
+ * @param {unknown} body
+ * @returns {boolean}
+ */
+export function asksForWork(body) {
+  const text = String(body == null ? "" : body).trim();
+  if (!text) return false;
+  if (NO_ACTION_PREFIX.test(text)) return false;
+  return IMPERATIVE.test(text) || REQUEST.test(text);
+}
+
+/**
+ * Is there enough here to be an ask at all?
+ * @param {unknown} body
+ * @returns {boolean}
+ */
+export function hasSubstance(body) {
+  const text = String(body == null ? "" : body).trim();
+  if (!text) return false;
+  if (NO_SUBSTANCE.test(text)) return false;
+  return text.length >= MIN_SUBSTANCE_CHARS;
+}
+
+// ---------------------------------------------------------------------------
+// The collective classifier
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {"roll-call"|"work"|"ambient"} CollectiveIntent
+ */
+
+/** The three intents, in the order a reader should meet them. */
+export const COLLECTIVE_INTENTS = Object.freeze(["roll-call", "work", "ambient"]);
+
+/**
+ * Phrases that ask each addressee to REPORT ON ITSELF. Excised from the body
+ * before the work gate runs (see rule 1), so a status ask that happens to use
+ * an action verb — "give me an UPDATE", "REVIEW your plate" — cannot read as a
+ * request to go and do something.
+ *
+ * Every one is anchored to a self-reference (`you`, `your`, `their`,
+ * `everyone`) or is a named ritual (roll call, standup, sound off). A bare
+ * "status" or "update" is NOT here: "update the binder" is work.
+ *
+ * @type {readonly RegExp[]}
+ */
+export const ROLL_CALL_PATTERNS = Object.freeze([
+  /\broll[ -]?call\b/gi,
+  /\bsound off\b/gi,
+  /\bstatus check\b/gi,
+  /\bstand[ -]?up\b/gi,
+  /\bcheck[ -]?in\b/gi,
+  /\bwho(?:'s| is| has| are)\b[^.!?\n]{0,24}\b(?:around|online|here|available|free|working)\b/gi,
+  /\bwhat\b[^.!?\n]{0,16}\b(?:you|they)(?:'re| are)?\b[^.!?\n]{0,12}\b(?:working on|doing|up to|on right now)\b/gi,
+  /\b(?:give|post|share|send|drop|leave)\b[^.!?\n]{0,24}\b(?:an?\s+|your\s+|their\s+)?(?:update|status)\b/gi,
+  /\b(?:update|status)\b[^.!?\n]{0,24}\bfrom (?:your|their|each|you)\b/gi,
+  /\b(?:update|status)s?\s*(?:please|pls|report)\b/gi,
+  /\bupdate on what\b/gi,
+  /\bwhat(?:'s| is)\b[^.!?\n]{0,16}\bblocking (?:you|everyone|anyone)\b/gi,
+  /\bwhat(?:'s| is) next on (?:your|their)\b/gi,
+  /\b(?:your|their) (?:top |current )?(?:priority|priorities|task|tasks|plate|plates|lane|lanes)\b/gi,
+  /\breport (?:your|their|back with your)\b/gi,
+  /\bconfirm you can (?:see|read|hear)\b/gi,
+  /\bwhere (?:is|are) (?:everyone|everybody|we all)\b/gi,
+  /\bdid (?:everyone|everybody|you all|all of you)\b/gi,
+]);
+
+/**
+ * Phrases that make a work-shaped sentence NOT an assignment. Read before the
+ * verb: this is the guard against "everyone should take a look sometime"
+ * minting thirteen rows, and it is deliberately the widest net here, because
+ * the asymmetry is real — a missed row costs one invisible ask, a spurious row
+ * costs thirteen and the owner's attention for the board itself.
+ *
+ * @type {readonly RegExp[]}
+ */
+export const HEDGE_PATTERNS = Object.freeze([
+  /\bsometime\b/i,
+  /\bat some point\b/i,
+  /\bwhen(?:ever)? (?:you|anyone|someone|folks|people)\b[^.!?\n]{0,20}\b(?:chance|moment|time|minute|min|sec|second|bandwidth|capacity)\b/i,
+  /\bno (?:rush|hurry|pressure|urgency|action|need)\b/i,
+  /\bif (?:anyone|anybody|someone|you)\b[^.!?\n]{0,24}\b(?:time|chance|moment|minute|min|sec|bandwidth|capacity|curious|interested|keen)\b/i,
+  /\bfeel free\b/i,
+  /\bno action (?:needed|required|necessary)\b/i,
+  /\bnothing (?:to do|needed|required)\b/i,
+  /\b(?:purely |just )?(?:fyi|for (?:your )?(?:info|information|awareness|visibility))\b/i,
+  /\bmight (?:want|be worth|be of interest)\b/i,
+  /\bworth a (?:look|read|skim)\b/i,
+  /\boptional\b/i,
+  /\bwhenever\b/i,
+  /\bif you(?:'re| are) (?:curious|interested|bored)\b/i,
+]);
+
+/**
+ * Does this body hedge hard enough that no verb in it is an assignment?
+ * @param {unknown} body
+ * @returns {boolean}
+ */
+export function isHedged(body) {
+  const text = typeof body === "string" ? body : "";
+  if (!text.trim()) return false;
+  return HEDGE_PATTERNS.some((re) => re.test(text));
+}
+
+/**
+ * The body with every roll-call phrase blanked out. Exported for the tests and
+ * for a log line: "we called this a roll-call, and here is what was left after
+ * the status phrasing came out" is the one sentence that makes a wrong verdict
+ * diagnosable without a debugger.
+ *
+ * @param {unknown} body
+ * @returns {string}
+ */
+export function withoutRollCallPhrases(body) {
+  let text = typeof body === "string" ? body : "";
+  if (!text.trim()) return "";
+  for (const re of ROLL_CALL_PATTERNS) {
+    // Every pattern is /g; `replace` with a global regex is stateless per call
+    // (it resets lastIndex itself), so these are safe as module constants —
+    // `test()` on a /g regex would NOT be, which is why nothing here calls it.
+    text = text.replace(re, " ");
+  }
+  return text;
+}
+
+/**
+ * Did any roll-call phrase appear at all?
+ * @param {unknown} body
+ * @returns {boolean}
+ */
+export function hasRollCallPhrase(body) {
+  const text = typeof body === "string" ? body : "";
+  if (!text.trim()) return false;
+  return withoutRollCallPhrases(text) !== text;
+}
+
+/**
+ * THE decision. Pure, total, and the only implementation on this plane.
+ *
+ * Call it ONLY for a message already known to be collectively addressed; for
+ * anything else the answer is meaningless (a 1:1 DM saying "review the binder"
+ * is directed work and the ordinary path owns it).
+ *
+ * @param {unknown} body
+ * @returns {{intent: CollectiveIntent, reason: string}}
+ */
+export function collectiveIntent(body) {
+  const text = (typeof body === "string" ? body : "").trim();
+  if (!text) return { intent: "ambient", reason: "empty" };
+
+  const rollCallPhrase = hasRollCallPhrase(text);
+
+  // A hedge beats every verb in the sentence — but NOT a roll-call. "everyone
+  // sound off whenever you get a sec" is still a roll-call; it just is not
+  // work, and a roll-call was never going to open a row anyway.
+  if (isHedged(text)) {
+    return rollCallPhrase
+      ? { intent: "roll-call", reason: "roll-call-phrase" }
+      : { intent: "ambient", reason: "hedged" };
+  }
+
+  const residue = rollCallPhrase ? withoutRollCallPhrases(text) : text;
+  if (hasSubstance(residue) && asksForWork(residue)) {
+    return { intent: "work", reason: "asks-for-work" };
+  }
+
+  if (rollCallPhrase) return { intent: "roll-call", reason: "roll-call-phrase" };
+  return { intent: "ambient", reason: "no-work-asked" };
+}
+
+/**
+ * Convenience: is this collective message WORK?
+ * @param {unknown} body
+ * @returns {boolean}
+ */
+export function isCollectiveWork(body) {
+  return collectiveIntent(body).intent === "work";
+}
+
+/**
+ * The intent of a flattened INBOX ITEM that the inbound join already decided is
+ * a broadcast (`isRollCallItem`). Returns null for anything that is not one —
+ * a DM, an @mention, a task comment — because the classifier's answer is only
+ * meaningful once the collective address is established.
+ *
+ * Lives here rather than in broadcast.mjs so that module stays what it is: the
+ * ADDRESS, with no opinion about what the address asked for.
+ *
+ * @param {object} item flattened inbox item
+ * @param {(item:object)=>boolean} isCollectiveItem usually `isRollCallItem`
+ * @returns {CollectiveIntent|null}
+ */
+export function itemCollectiveIntent(item, isCollectiveItem) {
+  if (typeof isCollectiveItem !== "function" || !isCollectiveItem(item)) return null;
+  const body = item && (item.content || item.text || item.subject);
+  return collectiveIntent(body).intent;
+}
+
+/**
+ * THE SHARED CORPUS. Literal strings, pinned by `collective.test.mjs` here and
+ * by hq's `src/server/work/collective.test.ts`. Every string is one a human
+ * could plausibly type into #general; every one already satisfies
+ * `isBroadcast`, so the only thing each pins is the intent.
+ *
+ * Same contract as BROADCAST_CORPUS: change a pattern on either plane and the
+ * other plane's test goes red until the two agree again.
+ */
+export const COLLECTIVE_CORPUS = Object.freeze({
+  /** WORK: every addressee opens a row of its own. */
+  work: Object.freeze([
+    "Everyone, please review the binder by Friday",
+    "Everybody: please update your KPI rows in the mandate before end of week",
+    "@here we need to draft the board pack today",
+    "@channel please push your branches before the 18:00 freeze",
+    "All of you: please audit your channel memberships this week",
+    "Team, please prepare your section of the deck before Thursday",
+    "the whole team needs to review the binder before Friday",
+    "Everyone, please review the binder and give me an update when it's done",
+    "@all please fix the failing checks on your own repos today",
+  ]),
+  /** ROLL-CALL: every addressee answers for itself; no rows. */
+  rollCall: Object.freeze([
+    "Can everyone give me an update on what they're doing right now (across sessions on your machines)?",
+    "did everyone see the deck?",
+    "Everybody: standup in 5",
+    "Quick one for all of you — what's blocking you today?",
+    "I'd like each of you to post your top priority",
+    "Thanks to the whole team for the push last night, what's next on your plates?",
+    "Team, quick check-in: what are you on?",
+    "@here who is around?",
+    "@channel status please",
+    "@all please confirm you can see this",
+    "all agents: report your current task",
+    "All colleagues, a quick update from your side please",
+    "roll call",
+    "Roll-call — sound off with what you're working on",
+    "status check: where is everyone at?",
+    "everyone sound off whenever you get a sec",
+  ]),
+  /** AMBIENT: addressed to the room, asking for nothing. No rows. */
+  ambient: Object.freeze([
+    "everyone should take a look at the binder sometime",
+    "Everyone, feel free to review the binder when you get a chance",
+    "FYI everyone — the binder is up in the drive",
+    "@here the deploy finished, no action needed",
+    "Everyone, the offsite is on Thursday at the usual place",
+    "@channel just publishing the notes for visibility",
+    "Everybody: nice work this week, genuinely",
+    "everyone might want to review the new brand kit at some point",
+    "@all optional: the reading group meets at 4",
+  ]),
+});
+
+export default {
+  COLLECTIVE_INTENTS,
+  COLLECTIVE_CORPUS,
+  ROLL_CALL_PATTERNS,
+  HEDGE_PATTERNS,
+  asksForWork,
+  hasSubstance,
+  isHedged,
+  withoutRollCallPhrases,
+  hasRollCallPhrase,
+  collectiveIntent,
+  isCollectiveWork,
+  itemCollectiveIntent,
+};