@cohortapp/agent-sdk 2.18.12 → 2.18.14

package/lib/identity/disclosure-scrub.mjs

@@ -0,0 +1,207 @@
+/**
+ * disclosure-scrub.mjs — remove a standing-self-identification INSTRUCTION from
+ * seat-local prose before it reaches the model.
+ *
+ * WHY A COUNTER-INSTRUCTION IS NOT ENOUGH
+ *   Two of the three prompt planes build their identity by scraping prose out of
+ *   the SEAT's own files — `## Identity` / `## Company Context` /
+ *   `## Communication Rules` from the seat's CLAUDE.md
+ *   (scripts/daemon/responder.mjs#loadPreamble,
+ *   scripts/daemon/prompt-builder.mjs#extractPreamble) and the per-sender YAML
+ *   under memory/profiles/users/. `maestro upgrade` deliberately never touches
+ *   either, so whatever a seat was scaffolded or hand-edited with in 2026-08
+ *   is still there and still first in the prompt.
+ *
+ *   Some seats were hand-edited, in good faith, to carry the disclosure opener
+ *   as a STANDING RULE — because for a while the send gate demanded it and the
+ *   only way past a gate that demands disclosure is to disclose. Shipping
+ *   `SELF_PRESENTATION` (lib/identity/persona.mjs) puts the correct rule in the
+ *   prompt, but it does not remove the seat-local one: the model is then handed
+ *   two contradictory instructions, the seat's one arrives ~700 characters
+ *   earlier, and on the full-session plane it lands immediately after the
+ *   sentence that declares the identity section authoritative. Adding text
+ *   cannot win that; removing the contradiction can.
+ *
+ * WHAT IS REMOVED, AND WHAT IS DELIBERATELY NOT
+ *   Removed: a LINE that reproduces one of the proactive-disclosure templates in
+ *   policies/ai-disclosure.yaml, or that instructs self-announcement in the
+ *   abstract ("open every message by introducing yourself as an AI assistant").
+ *
+ *   NOT removed: anything about answering honestly WHEN ASKED. That is the
+ *   non-overridable invariant in policies/ai-disclosure.yaml and it must survive
+ *   this scrub intact — {@link ASKED_SHAPE} exempts it explicitly. Scrubbing it
+ *   would turn a fix for an unprompted disclaimer into a licence to conceal,
+ *   which is the one thing nothing in this tree is allowed to do.
+ *
+ *   Also not removed: the external-first-contact duty as POLICY. This module
+ *   edits prompt text only. `lib/comms/send-gate` remains the thing that decides
+ *   when the line is actually owed, and it still demands it for an external
+ *   first contact.
+ *
+ * THE BANNED TEXT IS QUOTED NOWHERE HERE. The fragments are derived from
+ * policies/ai-disclosure.yaml at run time. A guard that reproduces the string it
+ * guards against is how the string gets reseeded — the next author reads it in a
+ * comment and writes it back in, in good faith.
+ *
+ * Pure core (`deriveDisclosureFragments`, `scrubDisclosureInstructions`) so the
+ * behaviour is testable without a filesystem; the I/O wrapper never throws and
+ * fails OPEN (shape rules only), because no scrub is worth failing a send.
+ */
+
+import { readFileSync } from "fs";
+import { fileURLToPath } from "url";
+import { join, dirname } from "path";
+
+/** The framework's own copy of the policy — NOT the seat's. */
+const PACKAGED_POLICY = join(dirname(fileURLToPath(import.meta.url)), "..", "..", "policies", "ai-disclosure.yaml");
+
+/**
+ * A line that is about answering a QUESTION is never scrubbed, whatever else it
+ * says. The truthfulness invariant reads exactly like a self-identification
+ * instruction to a dumb matcher, and it is the one line that must survive.
+ */
+const ASKED_SHAPE = /\b(?:if|when|whenever|should)\b[^.\n]{0,60}\b(?:ask|asks|asked|asking|question|questions|enquir|inquir)/i;
+
+/** The self-nature noun phrase an announcement instruction has to name. */
+const SELF_NATURE = /\b(?:an?\s+(?:ai|a\.i\.)\b|ai\s+(?:assistant|agent|bot|helper|colleague|model|system)|\bbot\b|\bchatbot\b|language model)/i;
+
+/** The act of putting it at the top of a message. */
+const ANNOUNCE_VERB = /\b(?:open(?:s|ing)?|begin(?:s|ning)?|start(?:s|ing)?|lead(?:s|ing)?\s+with|preface|precede|introduce|introducing|announce|announcing|identify\s+yourself|present\s+yourself|state\s+up\s+front|sign(?:s|ing)?\s+off|disclaimer|disclose)\b/i;
+
+/** Second-person/first-person orientation — an instruction ABOUT THE AGENT. */
+const SELF_REF = /\b(?:you|your|yourself|i'?m|i\s+am|my|me|myself|the\s+agent)\b/i;
+
+/** Minimum length of a derived policy fragment worth matching a line against. */
+const MIN_FRAGMENT = 14;
+
+/**
+ * Every proactive-disclosure template in the AI-disclosure policy, reduced to the
+ * literal prose an agent would have to write.
+ *
+ * Deliberately a dumb line scan rather than a YAML parse: the policy file is the
+ * INPUT to this derivation, so the derivation must not depend on the file being
+ * well-formed enough to parse. A malformed policy must degrade to "fewer
+ * fragments", never to a throw on the send path.
+ *
+ * @param {string} policyText  raw contents of policies/ai-disclosure.yaml
+ * @returns {string[]} distinctive lower-cased fragments
+ */
+export function deriveDisclosureFragments(policyText) {
+  const out = new Set();
+  const lines = String(policyText || "").split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    // The proactive templates only. `truthful_answer_template` is the INVARIANT's
+    // text — the honest answer to a direct question — and must never be scrubbed
+    // out of anything.
+    if (!/^\s*(identity_line|footer):\s*>/.test(lines[i])) continue;
+    const body = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      const l = lines[j];
+      if (l.trim() === "") break;
+      if (l.trim().startsWith("#")) break;       // a comment ends the block scalar
+      if (!/^\s{6,}\S/.test(l)) break;
+      body.push(l.trim());
+    }
+    for (const piece of body.join(" ").split(/\{[a-z_]+\}/i)) {
+      const p = piece.replace(/\s+/g, " ").replace(/^[\s—–,.:;'"-]+|[\s—–,.:;'"-]+$/g, "").toLowerCase();
+      if (p.length >= MIN_FRAGMENT) out.add(p);
+    }
+  }
+  return [...out];
+}
+
+/**
+ * Does this ONE line instruct (or render) a standing self-identification opener?
+ *
+ * @param {string} line
+ * @param {string[]} fragments  from {@link deriveDisclosureFragments}
+ * @returns {boolean}
+ */
+export function isDisclosureInstruction(line, fragments = []) {
+  const raw = String(line || "");
+  if (!raw.trim()) return false;
+  // The invariant is exempt, unconditionally and first.
+  if (ASKED_SHAPE.test(raw)) return false;
+
+  const lc = raw.toLowerCase();
+  for (const f of fragments) {
+    if (f && f.length >= MIN_FRAGMENT && lc.includes(f)) return true;
+  }
+  // Shape rule, for a hand-written variant the policy never contained. All three
+  // must hold on the SAME line: the act of announcing, the nature being
+  // announced, and the agent as the subject. Two of the three is ordinary prose
+  // ("the directory badges every AI member"), and scrubbing that would be
+  // vandalism of a perfectly good seat file.
+  return ANNOUNCE_VERB.test(raw) && SELF_NATURE.test(raw) && SELF_REF.test(raw);
+}
+
+/**
+ * The note left in place of whatever was removed. It names the SHAPE of the
+ * removed instruction and never reproduces it — see the module header.
+ */
+export const SCRUB_NOTE =
+  "[One or more lines of seat-local text were removed here: they instructed a standing self-identification opener. " +
+  "That instruction is stale — it dates from a period when the send gate demanded the line from internal recipients too " +
+  "(policies/ai-disclosure.yaml scopes the duty to an external first contact, and the send gate, not you, decides when it applies). " +
+  "The self-presentation rules elsewhere in this prompt are the current instruction and outrank any seat-local text. " +
+  "Answering honestly when someone sincerely asks whether you are an AI is unaffected and still required.]";
+
+/**
+ * Remove self-identification instructions from a block of seat-local prose.
+ *
+ * @param {string} text
+ * @param {string[]} fragments
+ * @returns {{ text: string, removed: string[] }} scrubbed text and the lines dropped
+ */
+export function scrubDisclosureInstructions(text, fragments = []) {
+  const src = String(text || "");
+  if (!src) return { text: src, removed: [] };
+  const kept = [];
+  const removed = [];
+  for (const line of src.split("\n")) {
+    if (isDisclosureInstruction(line, fragments)) { removed.push(line); continue; }
+    kept.push(line);
+  }
+  if (removed.length === 0) return { text: src, removed };
+  // Collapse the hole the removal left, then say that something was removed.
+  // Silence would be worse: a model that reads a truncated rule list has no way
+  // to tell an edit from an omission.
+  const body = kept.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+  return { text: `${body}\n\n${SCRUB_NOTE}`, removed };
+}
+
+let _fragments = null;
+/**
+ * The fragments from the PACKAGED policy, cached per process.
+ * Never throws: an unreadable policy yields `[]`, which leaves the shape rule in
+ * {@link isDisclosureInstruction} doing the work on its own.
+ *
+ * @param {string} [policyPath]
+ * @returns {string[]}
+ */
+export function loadDisclosureFragments(policyPath = PACKAGED_POLICY) {
+  if (_fragments && policyPath === PACKAGED_POLICY) return _fragments;
+  let frags = [];
+  try {
+    frags = deriveDisclosureFragments(readFileSync(policyPath, "utf-8"));
+  } catch {
+    frags = [];
+  }
+  if (policyPath === PACKAGED_POLICY) _fragments = frags;
+  return frags;
+}
+
+/**
+ * The convenience wrapper the two prompt planes call: scrub seat-local prose
+ * against the packaged policy. Never throws.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function scrubSeatText(text) {
+  try {
+    return scrubDisclosureInstructions(text, loadDisclosureFragments()).text;
+  } catch {
+    return String(text || "");
+  }
+}

package/lib/identity/persona.mjs

@@ -10,9 +10,11 @@
  *     1. A freshly-scaffolded repo has "*Configured by `maestro setup`*" sitting
  *        in those sections. The model was handed a near-empty identity and fell
  *        back to the generic-assistant register it ships with — introducing and
- *        signing itself as "an AI assistant working on behalf of <principal>",
- *        deferring on matters inside its own mandate, and writing to colleagues
- *        as a support function rather than as the person holding the role.
+ *        signing itself with a rendering of the `identity_line` template in
+ *        policies/ai-disclosure.yaml (not reproduced here; see
+ *        SELF_PRESENTATION_RULES below for why), deferring on matters inside its
+ *        own mandate, and writing to colleagues as a support function rather
+ *        than as the person holding the role.
  *
  *     2. Everything the org actually knows about the member — title, seniority
  *        band, background, tone of voice, responsibilities, operating principles,
@@ -97,6 +99,62 @@ function reportingLine(a) {
   return title ? `You report to ${name}, ${title}.` : `You report to ${name}.`;
 }
 
+/**
+ * SELF-PRESENTATION — the rules about how an agent refers to its own
+ * nature. Kept as a standalone frozen list, and exported as a ready-made block,
+ * for one reason: they must reach the model on EVERY prompt plane, including the
+ * ones that render no persona block at all.
+ *
+ * WHY THAT MATTERS, concretely. `renderPersona` returns "" when config/agent.json
+ * carries neither a name nor a title, and the quick-reply plane
+ * (scripts/daemon/responder.mjs) rendered no persona block by design. Both cases
+ * handed the model an identity vacuum, and a model in an identity vacuum falls
+ * back to the generic-assistant register it ships with — which is how a rendering
+ * of the `identity_line` template in policies/ai-disclosure.yaml came to open a
+ * mid-thread correction to the agent's own figures, in the organisation's own
+ * channel, to colleagues who provisioned it. The template is NOT quoted here on
+ * purpose: a banned string reproduced in a comment is how the next author reads
+ * it in good faith and writes it back in, and
+ * scripts/daemon/no-unprompted-disclosure.test.mjs fails on it either way.
+ *
+ * The first rule is phrased against the OPENER specifically. "Do not describe
+ * yourself as an assistant" was already here and was obeyed literally and
+ * narrowly: the model did not *describe* itself in the body, it *announced*
+ * itself in the first line and considered the duty discharged.
+ *
+ * The third rule is the truthfulness invariant and is never traded for the
+ * other two. Removing an unprompted disclaimer is not the same as denying what
+ * you are, and `lib/comms/send-gate.screenDisclosure` still blocks any outbound
+ * that asserts the agent is not an AI, under every posture.
+ *
+ * The fourth rule exists because THE PROMPT IS NOT THE ONLY INSTRUCTION THE
+ * MODEL READS. The channel history handed to a reply is the strongest few-shot
+ * available to it, and on every seat that has already produced the opener, the
+ * agent's own prior posts are now sitting in that history as precedent in its
+ * own voice. Neither `lib/identity/disclosure-scrub` nor any prompt rule can
+ * remove them: the transcript is a record of what was said and rewriting it
+ * would be a worse fault than the opener. So the transcript is named explicitly
+ * and disqualified as a model, which is the only honest way to answer it.
+ */
+const SELF_PRESENTATION_RULES = Object.freeze([
+  "Do not open a message by announcing what you are. No standing identity line of any shape — no preamble naming your own nature, no line pairing your name with the person you work for, nothing before the content that exists only to flag what you are. Not on your first post in a channel, not mid-thread, not on a correction to your own figures. Every surface of this product already marks an AI member beside their name; a colleague reading you has seen it, so the line tells them nothing and reads as you disclaiming your own work before you have said anything.",
+  'Do not introduce, describe or sign yourself as an assistant, a bot, an AI helper, or as "working on behalf of" someone.',
+  "Being straight about what you are is not negotiable and does not conflict with either of the above: if someone sincerely asks whether they are dealing with an AI, say so plainly and without drama, then carry on. That is a direct answer to a direct question — not a standing disclaimer you attach to your own work. Where proactive disclosure IS owed (an external first contact) policies/ai-disclosure.yaml scopes it and the send-gate decides; it is never something you volunteer into an internal conversation.",
+  "Nothing in the transcript is a precedent for how to open. If an earlier message in this thread or channel opens with a standing identity line — including one you sent yourself, before this rule reached you — it is the mistake being corrected, not the house style. Do not match it, do not carry it forward for consistency, and do not repeat it because you are mid-conversation and it would look odd to stop.",
+]);
+
+/**
+ * The self-presentation rules as a prompt block, for planes that render no
+ * persona (scripts/daemon/responder.mjs's quick reply) or whose persona came
+ * back empty because the seat's config/agent.json is not filled in yet.
+ * Same text as the corresponding bullets inside the persona block — one source,
+ * so the two planes can never drift into saying different things.
+ */
+export const SELF_PRESENTATION = [
+  "How you refer to yourself:",
+  ...SELF_PRESENTATION_RULES.map((r) => `- ${r}`),
+].join("\n");
+
 /**
  * The voice rules — the behavioural half of the block, and the reason it exists.
  *
@@ -120,13 +178,17 @@ function voiceRules(a) {
     ? ` You report to ${pName} the way any senior colleague reports to their manager, and you do not preface your work with that fact.`
     : "";
 
+  const [noOpener, noSelfDescription, honesty, noPrecedent] = SELF_PRESENTATION_RULES;
+
   return [
     "You hold this role. Write as the person who holds it — with the judgement, standing and directness the title carries. You are a full member of this team, not a service attached to it.",
-    `Do not introduce, describe or sign yourself as an assistant, a bot, an AI helper, or as "working on behalf of" someone.${reportsClause}`,
+    noOpener,
+    `${noSelfDescription}${reportsClause}`,
     "Do not position yourself as junior to whoever you are writing to, including your principal or the CEO. State what you did, what you found, and what you recommend. Ask for a decision only when the decision is genuinely theirs to make.",
     "Do not thank people for their patience, apologise for taking up their time, or hedge a finding you are confident in. Colleagues at your level do not do this, and it reads as a tell.",
     "Disagree when you disagree, and say so first rather than burying it under agreement. A concern you soften into politeness is a concern you failed to raise.",
-    "Being straight about what you are is not negotiable and does not conflict with any of the above: if someone sincerely asks whether they are dealing with an AI, say so plainly and without drama. That is a direct answer to a direct question — not a standing disclaimer you attach to your own work.",
+    honesty,
+    noPrecedent,
   ];
 }
 
@@ -273,4 +335,77 @@ export function loadPersonaBlock(agentRoot, opts = {}) {
   }
 }
 
-export const _test = { ALTITUDE_STANDING, personaProse, reportingLine, voiceRules, list };
+/**
+ * Scaffold sentinels — a value the scaffold ships as "UNCONFIGURED…" asserts
+ * nothing, and rendering it puts a lie in the prompt. Treat it as absent so
+ * `renderPersona`'s omit-when-unset rule fires.
+ * @param {unknown} v
+ * @returns {string} "" for an unset or sentinel value
+ */
+export function configuredStr(v) {
+  const t = typeof v === "string" ? v.trim() : "";
+  if (!t) return "";
+  if (/^unconfigured\b/i.test(t)) return "";
+  return t;
+}
+
+/** Strip scaffold sentinels out of a parsed config/agent.json. @param {object} a @returns {object} */
+export function scrubAgentConfig(a) {
+  const src = a && typeof a === "object" ? a : {};
+  const out = { ...src };
+  for (const k of ["firstName", "lastName", "fullName", "title", "company", "companyDescription", "persona", "background", "bio"]) {
+    if (k in out) out[k] = configuredStr(out[k]);
+  }
+  // A surname with no first name and no full name is not an identity — better
+  // to render no name at all than "You are AGENT." (the scaffold ships
+  // firstName "UNCONFIGURED" / lastName "AGENT").
+  if (!out.firstName && !out.fullName) out.lastName = "";
+  if (src.principal && typeof src.principal === "object") {
+    const p = { ...src.principal };
+    for (const k of ["firstName", "lastName", "fullName", "title"]) p[k] = configuredStr(p[k]);
+    out.principal = p;
+  }
+  return out;
+}
+
+/** Same, for a parsed config/company.json. @param {object} c @returns {object} */
+export function scrubCompanyConfig(c) {
+  const src = c && typeof c === "object" ? c : {};
+  const out = { ...src };
+  for (const k of ["name", "legalName", "description", "tagline", "industry", "stage"]) {
+    if (k in out) out[k] = configuredStr(out[k]);
+  }
+  return out;
+}
+
+/**
+ * Render the persona block for a SEAT — config/agent.json + config/company.json
+ * with scaffold sentinels scrubbed first, so an unconfigured field is OMITTED
+ * rather than asserted.
+ *
+ * Lives here rather than in scripts/daemon/prompt-builder.mjs because BOTH
+ * prompt-assembly paths need it and only one of them had it. The quick-reply
+ * responder used to build its identity by scraping `## Identity` out of the
+ * seat's CLAUDE.md, which on every seat is the scaffold template — unresolved
+ * `{{agent.fullName}}` tokens followed by "If those tokens are still
+ * unresolved, your identity has not been configured yet". That is precisely the
+ * condition this module's header documents as producing an agent that
+ * introduces and signs itself with a rendering of the policy's identity_line,
+ * and it reached every reactive reply the fleet sent.
+ *
+ * @param {string} root agent repo root
+ * @param {object} [opts] forwarded to renderPersona
+ * @returns {string} "" when nothing is configured
+ */
+export function renderSeatPersona(root, opts = {}) {
+  const read = (rel) => {
+    try { return JSON.parse(readFileSync(join(root, rel), "utf-8")); } catch { return {}; }
+  };
+  try {
+    return renderPersona(scrubAgentConfig(read("config/agent.json")), scrubCompanyConfig(read("config/company.json")), opts) || "";
+  } catch {
+    return "";
+  }
+}
+
+export const _test = { ALTITUDE_STANDING, personaProse, reportingLine, voiceRules, list, SELF_PRESENTATION_RULES };

package/lib/org/inbound/conversation-frame.mjs

@@ -0,0 +1,289 @@
+/**
+ * conversation-frame.mjs — the block that tells a reply prompt it is joining a
+ * conversation ALREADY IN PROGRESS, with people who already know who the agent is.
+ *
+ * WHY THIS EXISTS
+ *   Seats were posting a self-introduction into the middle of live threads — a
+ *   rendering of `channels.<c>.identity_line` from policies/ai-disclosure.yaml,
+ *   the opener naming the agent's own nature and pairing it with its principal
+ *   — on a release-status post and on a correction to the agent's
+ *   OWN earlier figures, in the org's own #risk-compliance channel. Removing the
+ *   send-gate that DEMANDED a disclosure line (2.18.9/2.18.12) stopped the gate
+ *   training the behaviour, but it did not give the model any reason to stop:
+ *   the quick-reply prompt never said this was an ongoing conversation.
+ *
+ *   Rendering the real prompt (scripts/daemon/responder.mjs #realGenerateResponse)
+ *   for a mid-thread channel reply showed why a competent model would introduce
+ *   itself there:
+ *     - the item's transcript arrived as a bare "Recent conversation history"
+ *       dump with no statement that the agent is a PARTICIPANT in it;
+ *     - the agent's own earlier turns were unmarked, so lines authored by the
+ *       seat read as a third party's;
+ *     - nothing named the surface as a room inside the agent's own organisation,
+ *       and nothing said the other speakers are colleagues;
+ *     - the standing instruction was "You are generating a direct response to
+ *       this message" — the frame of a one-shot, not of a turn in a thread.
+ *   A model handed a transcript it is not told it is part of behaves correctly
+ *   when it introduces itself. The defect is the frame, not the model.
+ *
+ * WHAT THIS IS NOT
+ *   It is NOT a disclosure policy and it must never render one. The truthfulness
+ *   invariant lives in policies/ai-disclosure.yaml and lib/comms/send-gate.mjs
+ *   and is untouched: a sincere question about whether someone is an AI is still
+ *   answered plainly, on any message, internal or external. What this block
+ *   suppresses is the UNPROMPTED self-introduction, which nobody asked for and
+ *   which no policy ever required inside the agent's own workspace.
+ *
+ * PURE. No I/O, no clock, no env — every input is a parameter, so the exact text
+ * a given item produces is a unit test (conversation-frame.test.mjs).
+ */
+
+/**
+ * A transcript line as both history renderers emit it: `[<iso>] <Name>: <text>`.
+ * The timestamp is optional because `thread_context` hydrators and the local
+ * interaction mirror both sometimes omit it.
+ */
+const SPEAKER_LINE = /^(\s*(?:\[[^\]]*\]\s*)?)([^:\n]{1,80}?):(\s|$)/;
+
+/** Trim to a string, "" for anything nullish/non-scalar. */
+function s(v) {
+  return typeof v === "string" ? v.trim() : "";
+}
+
+/** Drop a trailing "(you)" marker from a speaker label. @param {string} n @returns {string} */
+function stripOwnMarker(n) {
+  return String(n || "").replace(/\s*\(you\)\s*$/i, "").trim();
+}
+
+/**
+ * The speaker names in a transcript, in first-appearance order.
+ *
+ * Deliberately conservative: a line that does not match `[ts] Name:` contributes
+ * nothing rather than guessing, so a wrapped continuation line cannot invent a
+ * participant. Names are capped at 80 chars by the pattern itself.
+ *
+ * @param {string|null|undefined} transcript
+ * @returns {string[]}
+ */
+export function parseSpeakers(transcript) {
+  const out = [];
+  const seen = new Set();
+  for (const line of s(transcript).split("\n")) {
+    const m = SPEAKER_LINE.exec(line);
+    if (!m) continue;
+    const name = m[2].trim();
+    if (!name) continue;
+    const key = name.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    out.push(name);
+  }
+  return out;
+}
+
+/**
+ * Mark the agent's own turns in a transcript so the model can see that it is
+ * already IN this conversation.
+ *
+ * Only the speaker label is touched — the body is never rewritten, because the
+ * body is attacker-influenced inbound text and this function is not a sanitiser.
+ * A transcript with no line by `agentName` comes back byte-identical.
+ *
+ * @param {string|null|undefined} transcript
+ * @param {string|null|undefined} agentName
+ * @returns {string} "" when the transcript is empty
+ */
+export function markOwnTurns(transcript, agentName) {
+  const text = s(transcript);
+  const me = s(agentName);
+  if (!text || !me) return text;
+  const meKey = me.toLowerCase();
+  return text
+    .split("\n")
+    .map((line) => {
+      const m = SPEAKER_LINE.exec(line);
+      if (!m) return line;
+      const name = m[2].trim();
+      if (name.toLowerCase() !== meKey) return line;
+      // Already marked (re-entrant call, or an upstream renderer did it).
+      if (/\(you\)\s*$/.test(name)) return line;
+      return `${m[1]}${name} (you):${m[3]}${line.slice(m[0].length)}`;
+    })
+    .join("\n");
+}
+
+/**
+ * Drop from `threadContext` every line the channel history already carries.
+ *
+ * The quick-reply user content used to render BOTH blocks in full, and for a
+ * mid-thread channel reply they overlap almost completely: the same three or
+ * four turns arrived twice, worth up to COHORT_HISTORY_LIMIT ×
+ * COHORT_HISTORY_CHARS of budget, and read as two different records of the same
+ * exchange. Comparison is on the whole trimmed line, so a turn truncated to a
+ * different length in the two renderers is kept rather than silently dropped —
+ * a duplicate is cheap, a lost turn is not.
+ *
+ * @param {string|null|undefined} history
+ * @param {string|null|undefined} threadContext
+ * @returns {string} "" when nothing survives
+ */
+export function dedupeThreadAgainstHistory(history, threadContext) {
+  const thread = s(threadContext);
+  if (!thread) return "";
+  const seen = new Set(
+    s(history).split("\n").map((l) => l.trim()).filter(Boolean),
+  );
+  if (seen.size === 0) return thread;
+  const kept = thread.split("\n").filter((l) => {
+    const t = l.trim();
+    return t ? !seen.has(t) : false;
+  });
+  return kept.join("\n").trim();
+}
+
+/**
+ * Services whose INBOUND items are internal by construction.
+ *
+ * An item on the org plane reached this agent because hq's ACL put it in reach:
+ * it is a row inside the workspace the agent is a member of. There is no such
+ * thing as an inbound Cohort channel post from outside the org.
+ *
+ * Both spellings are live in the tree — `lib/org/messaging` says "cohort",
+ * `lib/org/tool-surface` says "cohort-org" — so both are listed rather than one
+ * of them being quietly wrong. (The same pair is enumerated in
+ * lib/comms/send-gate.mjs#classifyRecipient for the same reason.)
+ */
+const ORG_PLANE_SERVICES = new Set(["cohort", "cohort-org"]);
+
+/**
+ * Which branch of the frame this item gets: are the other speakers colleagues
+ * inside the agent's own organisation, or correspondents outside it?
+ *
+ * THIS IS NOT A SECURITY DECISION AND MUST NEVER BECOME ONE. It selects one
+ * sentence of prose. The gate that decides whether a message may be SENT, and
+ * which information-barrier walls apply, is lib/comms/send-gate.mjs — it runs on
+ * the outbound path, on the real recipient, and nothing here can relax it.
+ *
+ * WHY IT IS NOT SIMPLY `classifyRecipient(service, channel_id || channel)`.
+ * That was the first shape, and it is wrong in a way that says nothing when it
+ * misses. `classifyRecipient` is default-DENY: its Cohort case returns
+ * "internal" only for a cuid/uuid-shaped id, so an item projected WITHOUT a
+ * `channel_id` — or one carrying a human channel slug like "#risk-compliance" —
+ * fell to "external" and the frame told the agent that colleagues in its own
+ * #risk-compliance channel were outside correspondents. Default-deny is exactly
+ * right for a send gate and exactly wrong for a description of a room, because
+ * the failure is silent: the external branch still renders no disclosure and
+ * still says "no self-introduction", so nothing downstream goes red.
+ *
+ * So origin decides first, shape second. Off the org plane the gate's own
+ * predicate is used unchanged, and its default-deny is inherited — an email or
+ * an unrecognised handle is external, which is both conservative and true.
+ *
+ * PURE: the classifier is a PARAMETER, so this module still has no imports with
+ * state and the branch a given item takes is a unit test.
+ *
+ * @param {{service?:string, channel_id?:string, recipient?:string, channel?:string}} item
+ * @param {((channel:string, recipient:string)=>string)|null} [classify]
+ *        lib/comms/send-gate.mjs#classifyRecipient, injected
+ * @returns {"internal"|"external"}
+ */
+export function frameRecipientClass(item = {}, classify = null) {
+  const service = s(item.service).toLowerCase();
+  if (ORG_PLANE_SERVICES.has(service)) return "internal";
+  const handle = s(item.channel_id) || s(item.recipient) || s(item.channel);
+  if (!handle || typeof classify !== "function") return "external";
+  try {
+    return classify(service, handle) === "external" ? "external" : "internal";
+  } catch {
+    return "external";
+  }
+}
+
+/**
+ * How the room should be described to the model.
+ * @param {{service?:string, channel?:string, is_dm?:boolean}} item
+ * @returns {string}
+ */
+function surfaceLabel(item) {
+  const channel = s(item.channel);
+  const service = s(item.service) || "this workspace";
+  if (item.is_dm) {
+    return `a direct message on ${service}`;
+  }
+  return channel ? `the ${channel} channel on ${service}` : `a channel on ${service}`;
+}
+
+/**
+ * The frame block.
+ *
+ * BUDGET. Six lines of standing frame plus at most two derived lines — under
+ * ~120 tokens, and it is spent only when there is actually a conversation to
+ * frame (`turns > 0`). It is paid for several times over by
+ * `dedupeThreadAgainstHistory`, which removes a duplicate transcript worth up to
+ * ~1,200 tokens from the same prompt.
+ *
+ * WHAT IS INCLUDED — the four things the rendered prompt was missing and a model
+ * would otherwise have to infer: that the exchange is ongoing, that the agent is
+ * already a participant in it, who the other participants are, and whether they
+ * are colleagues inside the agent's own organisation.
+ *
+ * WHAT IS EXCLUDED, deliberately: the room's full member list (unbounded, and
+ * the speakers are what matters for a reply), member titles and profiles (the
+ * context compiler's job, and only for the sender), the channel topic/purpose
+ * (an extra round trip on a 60-second path), and anything about the agent's
+ * nature — see the module header.
+ *
+ * @param {object} o
+ * @param {object} o.item                    the inbox item
+ * @param {string} [o.agentName]             the seat's own full name
+ * @param {"internal"|"external"} [o.recipientClass="internal"]
+ * @param {string} [o.history]               channel transcript
+ * @param {string} [o.threadContext]         thread transcript (already deduped)
+ * @returns {string} "" when there is no prior conversation to frame
+ */
+export function conversationFrame({
+  item = {},
+  agentName = "",
+  recipientClass = "internal",
+  history = "",
+  threadContext = "",
+} = {}) {
+  const transcript = [s(history), s(threadContext)].filter(Boolean).join("\n");
+  if (!transcript) return "";
+
+  const me = s(agentName);
+  const meKey = me.toLowerCase();
+  // The transcript handed in has usually already been through markOwnTurns, so
+  // the agent's own label reads "<Name> (you)". Compare on the bare name or the
+  // seat lands in its own list of "others who have spoken here".
+  const all = parseSpeakers(transcript).map((n) => ({ name: n, key: stripOwnMarker(n).toLowerCase() }));
+  const speakers = all.filter((x) => x.key !== meKey).map((x) => stripOwnMarker(x.name));
+  const iHaveSpoken = meKey !== "" && all.some((x) => x.key === meKey);
+
+  const internal = recipientClass !== "external";
+  const who = internal
+    ? "The people in it are colleagues in your own organisation. They know who you are"
+    : "The people in it are already in correspondence with you";
+
+  const lines = [];
+  lines.push("## This conversation");
+  lines.push("");
+  lines.push(
+    `You are already part of this exchange — it is ${surfaceLabel(item)}, in progress. ${who}; they do not need to be told, and nobody has asked.`,
+  );
+  if (speakers.length > 0) {
+    lines.push(
+      `Others who have spoken here: ${speakers.slice(0, 8).join(", ")}${speakers.length > 8 ? ", and others" : ""}.`,
+    );
+  }
+  if (iHaveSpoken) {
+    lines.push(`Lines marked "(you)" below are your OWN earlier turns — you are continuing them, including when you are correcting one.`);
+  }
+  lines.push(
+    "Write the next turn and nothing else: no greeting, no preamble, no self-introduction, no statement of your role, your reporting line or what you are. Pick up where the thread left off.",
+  );
+
+  return lines.join("\n");
+}
+
+export const _test = { SPEAKER_LINE, surfaceLabel, ORG_PLANE_SERVICES };