@cohortapp/agent-sdk 2.10.0 → 2.11.1

package/scripts/daemon/cadence-handlers.test.mjs

@@ -445,6 +445,10 @@ test("messaging-inbound: pulls new directed items and routes them into the inbox
     { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
     {
       cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t", agentId: "me" } } },
+      // Fresh root → no inbound cursor. Seed from the push-channel head so the
+      // pull starts at "now" (not genesis). The stub stands in for
+      // lib/org/push.readCursor.
+      pushHeadImpl: () => 5,
       pullImpl: async () => ({ events: [ev1, ev2], nextCursor: 12 }),
       toInboxImpl: (e) => ({ id: e.message_id, service: "cohort", content: e.text }),
       writeImpl: (service, item) => written.push({ service, item }),
@@ -461,20 +465,67 @@ test("messaging-inbound: pulls new directed items and routes them into the inbox
   assert.equal(JSON.parse(readFileSync(cursorFile, "utf8")).cursor, 12);
 });
 
+test("messaging-inbound: FIRST RUN seeds the inbound cursor from the push-channel head (no backlog replay)", async () => {
+  const root = tmpRoot();
+  let pulledCursor = null;
+  const res = await guardMessagingInbound(
+    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
+    {
+      cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
+      // The push channel has advanced to seq 4200. A fresh install must start
+      // there, NOT at 0 (which would replay the whole org ledger).
+      pushHeadImpl: () => 4200,
+      pullImpl: async ({ cursor }) => { pulledCursor = cursor; return { events: [], nextCursor: cursor }; },
+      toInboxImpl: () => ({}),
+      writeImpl: () => { throw new Error("should not write an item"); },
+    },
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.decision, "inline");
+  assert.equal(pulledCursor, 4200, "the pull started at the push head, not at genesis");
+  const cursorFile = join(root, "state", "messaging", "inbound-cursor.json");
+  assert.ok(existsSync(cursorFile), "the seeded head is persisted so a crash cannot fall back to genesis");
+  assert.equal(JSON.parse(readFileSync(cursorFile, "utf8")).cursor, 4200);
+});
+
+test("messaging-inbound: FIRST RUN with no push head yet HOLDS the tick (never replays from genesis)", async () => {
+  const root = tmpRoot();
+  const res = await guardMessagingInbound(
+    { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
+    {
+      cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
+      pushHeadImpl: () => null, // push channel has not established a head yet
+      pullImpl: async () => { throw new Error("must not pull before a head exists"); },
+      toInboxImpl: () => ({}),
+      writeImpl: () => { throw new Error("must not write"); },
+    },
+  );
+  assert.equal(res.ok, true);
+  assert.equal(res.decision, "inline");
+  assert.equal(res.routed, 0);
+  assert.match(res.reason, /awaiting push-channel head/);
+  assert.ok(!existsSync(join(root, "state", "messaging", "inbound-cursor.json")), "no cursor seeded while we wait for a head");
+});
+
 test("messaging-inbound: no new directed items → inline, routed 0, cursor unchanged", async () => {
   const root = tmpRoot();
+  // A cursor already exists (not a first run), so seeding is skipped and the pull
+  // starts from the persisted seq. Nothing new → the cursor must not move.
+  const cursorFile = join(root, "state", "messaging", "inbound-cursor.json");
+  mkdirSync(join(root, "state", "messaging"), { recursive: true });
+  writeFileSync(cursorFile, JSON.stringify({ cursor: 9, updatedAt: "2026-01-01T00:00:00Z" }));
   const res = await guardMessagingInbound(
     { event: { cadence: "messaging-inbound" }, agentRoot: root, log: () => {} },
     {
       cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
-      pullImpl: async ({ cursor }) => ({ events: [], nextCursor: cursor }),
+      pullImpl: async ({ cursor }) => { assert.equal(cursor, 9, "pull starts from the persisted cursor"); return { events: [], nextCursor: cursor }; },
       toInboxImpl: () => ({}),
       writeImpl: () => { throw new Error("should not write"); },
     },
   );
   assert.equal(res.decision, "inline");
   assert.equal(res.routed, 0);
-  assert.ok(!existsSync(join(root, "state", "messaging", "inbound-cursor.json")), "no cursor write when nothing advanced");
+  assert.equal(JSON.parse(readFileSync(cursorFile, "utf8")).cursor, 9, "cursor unchanged when nothing advanced");
 });
 
 test("messaging-inbound: org not configured → inline no-op (fail-open)", async () => {
@@ -496,6 +547,7 @@ test("messaging-inbound: MESSAGING_INBOUND_ESCALATE=1 escalates when items arriv
       { event: { cadence: "messaging-inbound" }, agentRoot: tmpRoot(), log: () => {} },
       {
         cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
+        pushHeadImpl: () => 1,
         pullImpl: async () => ({ events: [{ message_id: "m1", text: "@me" }], nextCursor: 1 }),
         toInboxImpl: (e) => ({ id: e.message_id }),
         writeImpl: () => {},
@@ -514,6 +566,7 @@ test("messaging-inbound: fully fail-open (pull throws → inline, never throws)"
     { event: { cadence: "messaging-inbound" }, agentRoot: tmpRoot(), log: () => {} },
     {
       cfg: { org: { cohort: { enabled: true, base: "https://x", token: "t" } } },
+      pushHeadImpl: () => 3,
       pullImpl: async () => { throw new Error("network down"); },
     },
   );
@@ -737,6 +790,7 @@ test("messaging-inbound (JOINT 3): the DEFAULT reader is wide — no family filt
     {
       cfg: { org: { cohort: { enabled: true, base: "https://x.test", token: "t" } } },
       agentId: ME,
+      pushHeadImpl: () => 1, // fresh root: seed past genesis so the ledger read runs
       fetchImpl,
       toInboxImpl: (e) => ({ id: e.id, service: "cohort", kind: e.kind, content: e.text }),
       writeImpl: (service, item) => written.push({ service, item }),
@@ -765,6 +819,7 @@ test("messaging-inbound (JOINT 3): MESSAGING_INBOUND_WIDE=0 falls back to the na
       {
         cfg: { org: { cohort: { enabled: true, base: "https://x.test", token: "t" } } },
         agentId: "member-me",
+        pushHeadImpl: () => 1, // fresh root: seed past genesis so the read runs
         // The narrow reader pins family=messaging,calling on its URL; assert the
         // degradation is announced rather than inferred from an empty inbox.
         fetchImpl: async () => ({ ok: true, status: 200, headers: { get: () => "application/json" }, text: async () => JSON.stringify({ events: [], nextCursor: 0 }), json: async () => ({ events: [], nextCursor: 0 }) }),

package/scripts/daemon/classifier-identity.test.mjs

@@ -0,0 +1,137 @@
+/**
+ * classifier-identity.test.mjs — the classifier's frame of reference must be
+ * READ, not asserted.
+ *
+ * WHAT BROKE
+ *   `buildSystemPrompt()` opened with:
+ *     "You are a message classifier for ${agentName}, ${agentRole} (AI-operated)
+ *      at Northwind."
+ *   — a hardcoded employer sitting between two interpolated fields, on a file
+ *   that already loads config/agent.json two functions above. It matters more
+ *   than a naming slip: the classifier's `summary` is carried verbatim into
+ *   assurance.composeAck (text a waiting human reads) and board-mirror's board
+ *   row title, so a fabricated employer in the classifier's frame leaks into the
+ *   human ack and the org record.
+ *
+ * WHAT THESE TESTS PIN
+ *   1. GROUNDED — the employer comes from config/agent.json, and from
+ *      config/company.json when agent.json leaves `company` blank.
+ *   2. EMPTY — no employer configured ⇒ the "at <company>" clause is OMITTED
+ *      entirely. No sentinel, no default, no invented name.
+ *   3. No principal on record ⇒ no principal sentence at all.
+ *
+ * Run: node --test scripts/daemon/classifier-identity.test.mjs
+ */
+
+"use strict";
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { renderClassifierIdentityLine, buildSystemPrompt, _resetAgentRegistry } from "./classifier.mjs";
+
+function seat(agent, company) {
+  const root = mkdtempSync(join(tmpdir(), "clf-"));
+  mkdirSync(join(root, "config"), { recursive: true });
+  if (agent) writeFileSync(join(root, "config/agent.json"), JSON.stringify(agent));
+  if (company) writeFileSync(join(root, "config/company.json"), JSON.stringify(company));
+  return root;
+}
+
+// ── 1. GROUNDED ─────────────────────────────────────────────────────────────
+
+test("grounded: the employer is interpolated from config", () => {
+  const line = renderClassifierIdentityLine({
+    name: "Robin",
+    role: "VP Operations",
+    company: "Meridian Freight",
+    principal: { fullName: "Dana Lee", title: "CEO" },
+  });
+  assert.equal(
+    line,
+    "You are a message classifier for Robin, VP Operations (AI-operated) at Meridian Freight. " +
+      "Robin is the autonomous executive command layer for CEO Dana Lee.",
+  );
+});
+
+test("grounded: config/company.json supplies the employer when agent.json leaves it blank", () => {
+  const root = seat(
+    { firstName: "Robin", fullName: "Robin Okafor", title: "VP Operations", company: "" },
+    { name: "Meridian Freight" },
+  );
+  const prev = process.env.AGENT_DIR;
+  process.env.AGENT_DIR = root;
+  _resetAgentRegistry();
+  try {
+    // The whole system prompt, built by the real loader against real files.
+    const prompt = buildSystemPrompt();
+    assert.match(prompt, /^You are a message classifier for Robin, VP Operations \(AI-operated\) at Meridian Freight\./);
+  } finally {
+    if (prev === undefined) delete process.env.AGENT_DIR; else process.env.AGENT_DIR = prev;
+    _resetAgentRegistry();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+// ── 2. EMPTY — omit, never fake ─────────────────────────────────────────────
+
+test("empty: an unconfigured seat's system prompt names NO employer", () => {
+  const root = seat(
+    { firstName: "UNCONFIGURED", lastName: "AGENT", fullName: "Unconfigured Agent", title: "Unconfigured Role", company: "" },
+    { name: "UNCONFIGURED" },
+  );
+  const prev = process.env.AGENT_DIR;
+  process.env.AGENT_DIR = root;
+  _resetAgentRegistry();
+  try {
+    const prompt = buildSystemPrompt();
+    assert.doesNotMatch(prompt.split("\n")[0], / at /, "no employer clause at all");
+    assert.doesNotMatch(prompt, /UNCONFIGURED/);
+  } finally {
+    if (prev === undefined) delete process.env.AGENT_DIR; else process.env.AGENT_DIR = prev;
+    _resetAgentRegistry();
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test("empty: no employer configured ⇒ the 'at <company>' clause is dropped", () => {
+  const line = renderClassifierIdentityLine({ name: "Robin", role: "VP Operations", company: "" });
+  assert.equal(line, "You are a message classifier for Robin, VP Operations (AI-operated).");
+  assert.doesNotMatch(line, / at /);
+});
+
+test("empty: the scaffold's UNCONFIGURED sentinel counts as absent", () => {
+  const line = renderClassifierIdentityLine({ name: "Robin", role: "VP Operations", company: "UNCONFIGURED" });
+  assert.doesNotMatch(line, /UNCONFIGURED/);
+  assert.doesNotMatch(line, / at /);
+});
+
+test("empty: no principal on record ⇒ no principal sentence", () => {
+  const withNone = renderClassifierIdentityLine({ name: "Robin", role: "VP", principal: {} });
+  assert.doesNotMatch(withNone, /command layer/);
+
+  // The loader's "the principal" string is an ABSENCE marker, not a person.
+  const withPlaceholder = renderClassifierIdentityLine({
+    name: "Robin",
+    role: "VP",
+    principal: { firstName: "the principal", fullName: "the principal", title: "principal" },
+  });
+  assert.doesNotMatch(withPlaceholder, /command layer/);
+});
+
+test("empty: nothing at all still yields a coherent, non-fabricated line", () => {
+  const line = renderClassifierIdentityLine({});
+  assert.equal(line, "You are a message classifier for the agent, agent (AI-operated).");
+});
+
+// ── 3. The literal is gone from the source ──────────────────────────────────
+
+test("the classifier source carries no hardcoded employer", async () => {
+  const { readFileSync } = await import("node:fs");
+  const src = readFileSync(new URL("./classifier.mjs", import.meta.url), "utf8");
+  assert.doesNotMatch(src, /\bNorthwind\b/i);
+  assert.doesNotMatch(src, /\bPartnerCo\b/i);
+});

package/scripts/daemon/classifier.mjs

@@ -71,23 +71,68 @@ try {
 // peers list. Prevents cross-agent message interception in shared channels
 // (ib-20260418-cross-agent-routing).
 
-const AGENT_DIR = process.env.AGENT_DIR || process.env.AGENT_ROOT || resolve(__dirname, "../..");
+// Resolved lazily so a test (or a re-exec that re-points AGENT_DIR) sees the
+// current value rather than whatever env the module happened to load under.
+function agentDir() {
+  return process.env.AGENT_DIR || process.env.AGENT_ROOT || resolve(__dirname, "../..");
+}
+
+/**
+ * A config value the operator has not filled in yet. config/company.json ships
+ * `"name": "UNCONFIGURED"` in the scaffold and empty strings elsewhere, so BOTH
+ * shapes mean absent.
+ * @param {*} v @returns {string}
+ */
+function configuredStr(v) {
+  const s = typeof v === "string" ? v.trim() : "";
+  // The scaffold ships SENTINELS, not blanks: config/company.json has
+  // "UNCONFIGURED", config/agent.json has "UNCONFIGURED" / "Unconfigured Agent"
+  // / "Unconfigured Role". A sentinel is an absence and must never be rendered.
+  if (!s || /^unconfigured\b/i.test(s)) return "";
+  return s;
+}
+
+/** Read config/company.json (the company SOT). Never throws. */
+function loadCompanyConfig(dir) {
+  try {
+    return JSON.parse(readFileSync(resolve(dir, "config/company.json"), "utf-8"));
+  } catch {
+    return {};
+  }
+}
 
-let _agentIdentity = null;   // { name, slackId, role, fullName, principal: {…} }
+let _agentIdentity = null;   // { name, slackId, role, fullName, company, principal: {…} }
 let _peerAgents = [];         // [{ name, slackId, role }] — all agents EXCEPT me
 
+/** For tests: drop the cached registry so a fresh AGENT_DIR is re-read. */
+export function _resetAgentRegistry() {
+  _agentIdentity = null;
+  _peerAgents = [];
+}
+
 function loadAgentRegistry() {
   if (_agentIdentity) return; // already loaded
+  const dir = agentDir();
 
   // 1. Primary: load THIS agent's identity from config/agent.json (SOT).
   try {
-    const me = JSON.parse(readFileSync(resolve(AGENT_DIR, "config/agent.json"), "utf-8"));
+    const me = JSON.parse(readFileSync(resolve(dir, "config/agent.json"), "utf-8"));
     _agentIdentity = {
-      name: me.firstName,
-      fullName: me.fullName,
+      // Scrubbed to "" when unset — each consumer then picks its own honest
+      // default (a generic noun in prose; NO match at all in the @-mention test,
+      // which must never widen because identity is missing).
+      name: configuredStr(me.firstName),
+      fullName: configuredStr(me.fullName),
       slackId: me.slackMemberId || "",
-      role: me.title || "agent",
+      role: configuredStr(me.title),
       repo: me.repoSlug,
+      // The employer, from the SAME object the name and role come from — and
+      // config/company.json when agent.json leaves it blank. It used to be
+      // a hardcoded example-company literal in the prompt below while
+      // everything around it was interpolated. INTERNAL classification comes
+      // from CONFIG, never a hardcoded company (the same doctrine as
+      // scripts/poller/gmail-poller.mjs#internalDomains).
+      company: configuredStr(me.company) || configuredStr(loadCompanyConfig(dir).name),
       principal: me.principal
         ? {
             firstName: me.principal.firstName || "the principal",
@@ -99,13 +144,14 @@ function loadAgentRegistry() {
   } catch {
     // Backwards compatibility for repos that haven't migrated yet.
     try {
-      const agentTs = readFileSync(resolve(AGENT_DIR, "config/agent.ts"), "utf-8");
+      const agentTs = readFileSync(resolve(dir, "config/agent.ts"), "utf-8");
       const nameMatch = agentTs.match(/firstName:\s*['"](\w+)['"]/);
       const slackMatch = agentTs.match(/slackMemberId:\s*['"]([^'"]+)['"]/);
       _agentIdentity = {
         name: nameMatch ? nameMatch[1] : "Agent",
         slackId: slackMatch ? slackMatch[1] : "",
         role: "agent",
+        company: configuredStr(loadCompanyConfig(dir).name),
         principal: { firstName: "the principal", fullName: "the principal", title: "principal" },
       };
     } catch {
@@ -113,6 +159,7 @@ function loadAgentRegistry() {
         name: "Agent",
         slackId: "",
         role: "agent",
+        company: configuredStr(loadCompanyConfig(dir).name),
         principal: { firstName: "the principal", fullName: "the principal", title: "principal" },
       };
     }
@@ -122,7 +169,7 @@ function loadAgentRegistry() {
   // maintains its own peer registry (shipped via `npx @cohortapp/agent-sdk upgrade`).
   let agents = [];
   try {
-    const raw = readFileSync(resolve(AGENT_DIR, "config/known-agents.json"), "utf-8");
+    const raw = readFileSync(resolve(dir, "config/known-agents.json"), "utf-8");
     agents = JSON.parse(raw).agents || [];
   } catch { /* not present — proceed without peer filtering */ }
 
@@ -131,7 +178,7 @@ function loadAgentRegistry() {
     ? agents.filter(a => a.slackId !== mySlackId)
     : agents;
 
-  console.log(`[classifier] Agent identity: ${_agentIdentity.name} (${_agentIdentity.slackId || "no slack ID"}), ${_peerAgents.length} peer agents`);
+  console.log(`[classifier] Agent identity: ${_agentIdentity.name || "(unconfigured)"} (${_agentIdentity.slackId || "no slack ID"}), ${_peerAgents.length} peer agents`);
 }
 
 const ANTHROPIC_MODEL = "claude-haiku-4-5-20251001";
@@ -142,10 +189,41 @@ const CLAUDE_CLI_TIMEOUT_MS = 30_000;
 
 // ── System prompt shared by both LLM classifiers ────────────────────────────
 
+/**
+ * The classifier's identity sentence. Pure, so the omission rule is testable.
+ *
+ * The employer is INTERPOLATED FROM CONFIG or the clause is dropped entirely —
+ * it was a hardcoded example-company literal sitting between two interpolated
+ * fields. This
+ * is not cosmetic: the classifier's `summary` is carried verbatim into
+ * assurance.composeAck (text a human reads) and board-mirror's board row title,
+ * so a fabricated employer in its frame of reference leaks into the org record.
+ *
+ * @param {{name?:string, role?:string, company?:string, principal?:object}} id
+ * @returns {string}
+ */
+export function renderClassifierIdentityLine(id) {
+  const agentName = configuredStr(id && id.name) || "the agent";
+  const agentRole = configuredStr(id && id.role) || "agent";
+  const company = configuredStr(id && id.company);
+  const p = (id && id.principal && typeof id.principal === "object") ? id.principal : {};
+  const pFull = configuredStr(p.fullName);
+  const pTitle = configuredStr(p.title);
+
+  const at = company ? ` at ${company}` : "";
+  const lines = [`You are a message classifier for ${agentName}, ${agentRole} (AI-operated)${at}.`];
+  // Only assert a principal when one is actually on record — the loader's
+  // "the principal" placeholder is an absence, not a person.
+  if (pFull && pFull !== "the principal") {
+    const who = pTitle && pTitle !== "principal" ? `${pTitle} ${pFull}` : pFull;
+    lines.push(`${agentName} is the autonomous executive command layer for ${who}.`);
+  }
+  return lines.join(" ");
+}
+
 function buildSystemPrompt() {
   loadAgentRegistry();
-  const agentName = _agentIdentity.name;
-  const agentRole = _agentIdentity.role || "agent";
+  const agentName = configuredStr(_agentIdentity.name) || "the agent";
   const principalName = _agentIdentity.principal.firstName;
   const principalFullName = _agentIdentity.principal.fullName;
   const principalTitle = _agentIdentity.principal.title;
@@ -155,7 +233,7 @@ function buildSystemPrompt() {
     ? `\nKNOWN PEER AGENTS (other AI agents in the organisation — if a message @-mentions one of these by name or Slack ID, it is NOT directed at ${agentName}):\n${_peerAgents.map(a => `- ${a.name} (${a.role}, Slack: <@${a.slackId}>)`).join("\n")}\n`
     : "";
 
-  return `You are a message classifier for ${agentName}, ${agentRole} (AI-operated) at Northwind. ${agentName} is the autonomous executive command layer for ${principalTitle} ${principalFullName}.
+  return `${renderClassifierIdentityLine(_agentIdentity)}
 
 Your job: classify each incoming message and return a JSON object with exactly these fields:
 
@@ -212,7 +290,7 @@ DIRECTED_AT_AGENT (CRITICAL — determines whether ${agentName} should respond.
 
 Context:
 - sender_privilege "ceo" = ${principalFullName} (always critical, always opus)
-- sender_privilege "leadership" = Sam (CFO/CIO/SEO), Jordan (GC), Casey (PartnerCo) — usually high priority
+- sender_privilege "leadership" = executive-team senders (CFO, CIO, General Counsel, and equivalent function heads) — usually high priority
 - sender_privilege "team" = internal team members
 - sender_privilege "external" = partners, candidates, advisors, vendors
 - sender_privilege "unknown" = unrecognised sender
@@ -273,7 +351,7 @@ function formatItemPrompt(item) {
   ];
   // Indicate channel type so the classifier can assess directed-ness
   loadAgentRegistry();
-  const agentName = _agentIdentity.name;
+  const agentName = configuredStr(_agentIdentity.name) || "the agent";
   if (item.is_dm) {
     parts.push(`Channel type: Direct message (1:1 with ${agentName})`);
   } else if (item.is_group) {
@@ -530,10 +608,13 @@ function isDirectedAtAgent(item) {
 
   // Explicit @mention or name mention in the message content
   const content = (item.content || "").toLowerCase();
-  const myName = (_agentIdentity.name || "agent").toLowerCase();
+  // FAIL CLOSED on an unconfigured name. The old fallback was the bare word
+  // "agent", so an unnamed seat matched any message containing "agent" and
+  // treated it as addressed to itself. No name on record ⇒ no name match.
+  const myName = configuredStr(_agentIdentity.name).toLowerCase();
   const mySlackId = (_agentIdentity.slackId || "").toLowerCase();
 
-  if (content.includes(myName)) return true;
+  if (myName && content.includes(myName)) return true;
   if (mySlackId && content.includes(mySlackId.toLowerCase())) return true;
 
   // Gmail/calendar messages are directed at the current agent (they're in its inbox)
@@ -630,7 +711,7 @@ function classifyWithRules(item) {
 }
 
 // Export for use in daemon's pre-classification gate
-export { isDirectedAtAgent, mentionsOtherAgent, loadAgentRegistry };
+export { isDirectedAtAgent, mentionsOtherAgent, loadAgentRegistry, buildSystemPrompt };
 
 // ── Main export ─────────────────────────────────────────────────────────────
 

package/scripts/daemon/inbox-deferral.mjs

@@ -199,38 +199,63 @@ export function promoteDeferred(channel, agentRoot) {
       matches.push({
         file,
         timestamp: readScalar(body, "timestamp") || "",
+        // THE SURFACE within the channel. `channel_id` names the ROOM; a single
+        // room carries several independent conversations at once — a directed 1:1
+        // DM thread AND the actor's own doc/board/decision events that resolve to
+        // the same channel_id. Bundling "latest-wins across the whole channel"
+        // folded those unrelated surfaces into one and silently dropped
+        // (`.processed-bundled`) a directed DM because a newer doc-comment event
+        // arrived in the same room. thread_context only ever carries the SAME
+        // thread's history, so bundling is sound ONLY within one surface. Key on
+        // thread_id, else the surface's own scope_id, else "" (a bare-channel
+        // burst — the original same-thread case, preserved).
+        surface:
+          readScalar(body, "thread_id") ||
+          readScalar(body, "scope_id") ||
+          "",
       });
     }
     if (matches.length === 0) continue;
 
-    // Latest-wins: lex-sort ISO timestamps, take the most recent.
-    matches.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
-    const latest = matches[matches.length - 1];
-    const older = matches.slice(0, -1);
-
-    // Promote the latest back to live inbox.
-    try {
-      const live = latest.file.replace(/\.deferred$/, "");
-      renameSync(join(inboxDir, latest.file), join(inboxDir, live));
-      result.promoted++;
-      result.service = service;
-    } catch {
-      // If the rename failed (race with another process), leave it
-      // as .deferred — the next session-close will retry.
+    // Group by surface within the channel, then bundle latest-wins WITHIN each
+    // group. Distinct surfaces each promote their own latest; none is dropped
+    // just because a newer message landed on a different surface in the room.
+    const groups = new Map();
+    for (const m of matches) {
+      if (!groups.has(m.surface)) groups.set(m.surface, []);
+      groups.get(m.surface).push(m);
     }
 
-    // Mark older bursts as bundled — their content is already part of
-    // the latest item's thread_context, so they don't need their own
-    // session, but we preserve the file for audit.
-    for (const m of older) {
+    for (const group of groups.values()) {
+      // Latest-wins: lex-sort ISO timestamps, take the most recent.
+      group.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+      const latest = group[group.length - 1];
+      const older = group.slice(0, -1);
+
+      // Promote the latest back to live inbox.
       try {
-        renameSync(
-          join(inboxDir, m.file),
-          join(inboxDir, m.file.replace(/\.deferred$/, ".processed-bundled"))
-        );
-        result.bundled++;
+        const live = latest.file.replace(/\.deferred$/, "");
+        renameSync(join(inboxDir, latest.file), join(inboxDir, live));
+        result.promoted++;
+        result.service = service;
       } catch {
-        // Best-effort; missing file is fine.
+        // If the rename failed (race with another process), leave it
+        // as .deferred — the next session-close will retry.
+      }
+
+      // Mark older bursts as bundled — their content is already part of
+      // the latest item's thread_context, so they don't need their own
+      // session, but we preserve the file for audit.
+      for (const m of older) {
+        try {
+          renameSync(
+            join(inboxDir, m.file),
+            join(inboxDir, m.file.replace(/\.deferred$/, ".processed-bundled"))
+          );
+          result.bundled++;
+        } catch {
+          // Best-effort; missing file is fine.
+        }
       }
     }
   }

package/scripts/daemon/inbox-deferral.test.mjs

@@ -12,11 +12,13 @@ function makeAgentRoot() {
   return root;
 }
 
-function writeInboxItem(root, name, { channel_id, timestamp, id = "test-id" }) {
+function writeInboxItem(root, name, { channel_id, timestamp, id = "test-id", thread_id, scope_id }) {
   const body = [
     `id: "${id}"`,
     `service: "slack"`,
     `channel_id: "${channel_id}"`,
+    ...(thread_id ? [`thread_id: "${thread_id}"`] : []),
+    ...(scope_id ? [`scope_id: "${scope_id}"`] : []),
     `timestamp: "${timestamp}"`,
     `content: |`,
     `  body`,
@@ -118,6 +120,42 @@ test("promoteDeferred with multiple items: keeps latest, bundles rest", () => {
   }
 });
 
+test("promoteDeferred bundles WITHIN a surface, not across the whole channel", () => {
+  // A directed 1:1 DM thread AND the actor's doc-comment events resolve to the
+  // same channel_id. Bundling latest-wins across the channel would drop the DM
+  // just because a newer doc event landed. Each surface must promote its own
+  // latest; nothing is bundled across surfaces.
+  const root = makeAgentRoot();
+  try {
+    // The directed DM (one message, thread T-DM).
+    writeInboxItem(root, "dm-1.yaml.deferred", {
+      channel_id: "room-1", thread_id: "T-DM", id: "dm-1",
+      timestamp: "2026-05-13T00:00:30Z",
+    });
+    // Two doc-comment events on the same room but a different surface (scope S-DOC),
+    // the later of which would have "won" under the old channel-wide bundling.
+    writeInboxItem(root, "doc-1.yaml.deferred", {
+      channel_id: "room-1", scope_id: "S-DOC", id: "doc-1",
+      timestamp: "2026-05-13T00:01:00Z",
+    });
+    writeInboxItem(root, "doc-2.yaml.deferred", {
+      channel_id: "room-1", scope_id: "S-DOC", id: "doc-2",
+      timestamp: "2026-05-13T00:02:00Z",
+    });
+    const r = promoteDeferred("room-1", root);
+    assert.equal(r.promoted, 2, "the DM and the latest doc event are BOTH promoted");
+    assert.equal(r.bundled, 1, "only the older doc event (same surface) is bundled");
+    const files = readdirSync(join(root, "state", "inbox", "slack")).sort();
+    assert.deepEqual(files, [
+      "dm-1.yaml",                    // the directed DM survives — NOT dropped
+      "doc-1.yaml.processed-bundled", // older doc event folded into doc-2
+      "doc-2.yaml",                   // latest doc event promoted
+    ]);
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+});
+
 test("promoteDeferred ignores items in other channels", () => {
   const root = makeAgentRoot();
   try {