@cohortapp/agent-sdk 2.15.0 → 2.17.0

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

@@ -15,7 +15,18 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 
-import { hydrate, clip, renderThread, describeBoardKind, describeApprovalKind } from "./hydrate.mjs";
+import {
+  hydrate,
+  clip,
+  renderThread,
+  priorComments,
+  isCommentKind,
+  htmlToText,
+  clampDocHtml,
+  DOC_HTML_MAX_CHARS,
+  describeBoardKind,
+  describeApprovalKind,
+} from "./hydrate.mjs";
 import { classifyEvent } from "./directedness.mjs";
 
 const ME = "M-me";
@@ -46,7 +57,9 @@ function facts(over = {}) {
     me: ME,
     myNames: [],
     channels: new Map(),
+    visibleChannelIds: null,
     channelPages: new Map(),
+    myEvents: null,
     myThreadRootIds: new Set(),
     tasks: null,
     decisions: null,
@@ -451,3 +464,445 @@ test("event-kind phrasing is stable and total", () => {
   assert.match(describeApprovalKind("approval.requested"), /waiting on you/);
   assert.match(describeApprovalKind("approval.rejected"), /REJECTED/);
 });
+
+// ---------------------------------------------------------------------------
+// the slice(0,-1) guard — four surfaces used to lose their newest comment
+//
+// `renderThread(comments.slice(0,-1))` assumed the event was always a comment.
+// It is not: item.assigned, item.moved, file.shared and decision.signed are
+// events ABOUT an entity that HAS a thread, and for those the newest comment is
+// context, not the trigger. On a freshly assigned task with one comment, that
+// comment was the whole of the context and the agent saw none of it.
+// ---------------------------------------------------------------------------
+
+test("item.assigned KEEPS its newest comment — it is context, not the trigger", async () => {
+  const f = facts({ tasks: new Map([["T-1", { id: "T-1", title: "Ship the thing", col: "todo" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [{ id: "c1", authorName: "Casey", body: "the client needs this by Friday" }] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.assigned", entity_id: "T-1", payload: { actor: THEM, assignee: ME } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_assigned", reason: "assignee" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.threadContext, /Casey: the client needs this by Friday/);
+  assert.equal(h.isReply, true);
+});
+
+test("item.moved keeps its newest comment", async () => {
+  const f = facts({ tasks: new Map([["T-2", { id: "T-2", title: "Rework", col: "blocked" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [{ id: "c9", authorName: "Casey", body: "moving this back, the numbers are wrong" }] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.moved", entity_id: "T-2", payload: { actor: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "assignee" }, facts: f, io });
+  assert.match(h.threadContext, /the numbers are wrong/);
+});
+
+test("file.shared keeps its newest comment", async () => {
+  const f = facts({ fileAcl: new Map([["F-1", { ownerId: ME, shared: true, name: "Q3 plan", kind: "DOC" }]]) });
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "read section two first" }] }),
+    "files.docRead": () => okFrame({ html: "<p>Q3 plan</p>" }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "file.shared", entity_id: "F-1", payload: { actor: THEM, name: "Q3 plan" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "shared" }, facts: f, io });
+  assert.match(h.threadContext, /Casey: read section two first/);
+});
+
+test("decision.signed keeps its newest comment", async () => {
+  const f = facts({ decisions: new Map([["D-1", { id: "D-1", title: "Pick a vendor", status: "signed" }]]) });
+  const io = fakeIo({
+    "decision.listComments": () => okFrame({ comments: [{ id: "d1", authorName: "Casey", body: "signing on the understanding we revisit in Q4" }] }),
+  });
+  const c = classifyEvent(ev({ family: "decision", kind: "decision.signed", entity_id: "D-1", payload: { actor: THEM, signedBy: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "decision", reason: "voice" }, facts: f, io });
+  assert.match(h.threadContext, /revisit in Q4/);
+});
+
+test("a comment event still drops its OWN comment from the context", async () => {
+  const f = facts({ tasks: new Map([["T-3", { id: "T-3", title: "Ship it" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Isla", body: "first pass is up" },
+      { id: "c2", authorName: "Casey", body: "any update?" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-3", payload: { actor: THEM } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "assignee" }, facts: f, io });
+  assert.match(h.threadContext, /first pass is up/);
+  assert.doesNotMatch(h.threadContext, /any update\?/, "the trigger is not its own context");
+});
+
+test("the payload's commentId drops the RIGHT comment when a newer one raced in", async () => {
+  const f = facts({ tasks: new Map([["T-4", { id: "T-4", title: "Ship it" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Isla", body: "first pass is up" },
+      { id: "c2", authorName: "Casey", body: "the trigger comment" },
+      { id: "c3", authorName: "Dana", body: "landed while we were reading" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "board", kind: "item.commented", entity_id: "T-4", payload: { actor: THEM, commentId: "c2" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "task_comment", reason: "assignee" }, facts: f, io });
+  assert.match(h.threadContext, /first pass is up/);
+  assert.match(h.threadContext, /landed while we were reading/);
+  assert.doesNotMatch(h.threadContext, /the trigger comment/);
+});
+
+// ---------------------------------------------------------------------------
+// pure guards
+// ---------------------------------------------------------------------------
+
+test("priorComments never mutates the caller's array", () => {
+  const rows = [{ id: "a" }, { id: "b" }];
+  const out = priorComments(rows, { kind: "item.commented" });
+  assert.equal(rows.length, 2);
+  assert.equal(out.length, 1);
+});
+
+test("isCommentKind knows the six kinds that ARE comments", () => {
+  for (const k of ["item.commented", "board.commented", "file.commented", "doc.comment", "decision.comment", "decision.adjustment_requested"]) {
+    assert.equal(isCommentKind(k), true, k);
+  }
+  for (const k of ["item.assigned", "item.moved", "file.shared", "decision.signed", "", null]) {
+    assert.equal(isCommentKind(k), false, String(k));
+  }
+});
+
+test("htmlToText keeps the prose and drops the markup", () => {
+  assert.equal(htmlToText("<h1>Title</h1><p>One &amp; two</p><p>Three</p>"), "Title\nOne & two\nThree");
+  assert.equal(htmlToText("<script>bad()</script><p>ok</p>"), "ok");
+  assert.equal(htmlToText(null), "");
+});
+
+// ---------------------------------------------------------------------------
+// call — participants, the room, and the transcript
+// ---------------------------------------------------------------------------
+
+test("a call carries the roster, the room's recent messages and the transcript", async () => {
+  const msgs = [
+    { id: "m1", authorId: THEM, authorName: "Casey", body: "can we talk through the pricing", createdAt: "2026-08-11T09:00:00.000Z" },
+    { id: "m2", authorId: ME, authorName: "Isla", body: "yes — starting a huddle", createdAt: "2026-08-11T09:01:00.000Z" },
+  ];
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  f.channels.set("C-eng", { id: "C-eng", kind: "PUBLIC", name: "engineering" });
+  f.channelPages.set("C-eng", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const io = fakeIo({
+    "calling.getDetails": () => okFrame({ callId: "CALL-1", live: true, participantCount: 2, participants: [
+      { kind: "MEMBER", memberId: THEM, inCall: true },
+      { kind: "GUEST", contactId: "contact-9", inCall: true },
+    ] }),
+    "calling.getTranscript": () => okFrame({ lines: [
+      { id: "l1", memberName: "Casey", text: "the list price is wrong on tier two", at: "2026-08-11T09:02:00.000Z" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-1", payload: { actor: THEM, channelId: "C-eng", topic: "pricing" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "call", reason: "member" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Call invite: pricing/);
+  assert.match(h.text, new RegExp(`In the call: ${THEM}, contact-9`));
+  assert.match(h.threadContext, /Casey: can we talk through the pricing/);
+  assert.match(h.threadContext, /Call transcript so far:/);
+  assert.match(h.threadContext, /the list price is wrong on tier two/);
+  assert.equal(io.calls.filter((k) => k.method === "messaging.history").length, 0, "the page was already in hand");
+});
+
+test("a call whose probes all fail still hydrates — fail-open, never blank", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  f.channels.set("C-eng", { id: "C-eng", kind: "PUBLIC", name: "engineering" });
+  const io = fakeIo({}); // every method NOT_FOUND
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-2", payload: { actor: THEM, channelId: "C-eng", topic: "standup" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "call", reason: "member" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Call invite: standup/);
+  assert.equal(h.threadContext, null);
+});
+
+test("a call in a room outside my roster is never paged for history", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-mine"]) });
+  const io = fakeIo({ "calling.getDetails": () => okFrame({ participants: [] }) });
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-3", payload: { actor: THEM, channelId: "C-not-mine", topic: "x" } }));
+  await hydrate({ candidate: c, verdict: { surface: "call", reason: "invited" }, facts: f, io });
+  assert.equal(io.calls.some((k) => k.method === "messaging.history"), false, "a room outside the roster must never be touched");
+});
+
+test("an UNREADABLE roster is not permission — no room is paged when visibleChannelIds is null", async () => {
+  // The guard read `visible instanceof Set && !visible.has(id)`, so the null
+  // case — the roster call failed, or has not run — fell straight through into
+  // `messaging.history` on a channel id that arrived on the EVENT PAYLOAD.
+  // facts.mjs enforces the opposite (`if (!visible) … return`) and this file's
+  // own docstring claimed it; now the code does too.
+  const f = facts({ visibleChannelIds: null });
+  const io = fakeIo({ "calling.getDetails": () => okFrame({ participants: [] }) });
+  const c = classifyEvent(ev({ family: "calling", kind: "start", entity_id: "CALL-4", payload: { actor: THEM, channelId: "C-PRIVATE-NOT-MINE", topic: "x" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "call", reason: "invited" }, facts: f, io });
+  assert.equal(h.ok, true, "declining a read is not a failed hydration");
+  assert.equal(
+    io.calls.some((k) => k.method === "messaging.history"),
+    false,
+    "an unknown roster must decline, not page an arbitrary payload-supplied channel",
+  );
+});
+
+test("an UNREADABLE roster is not permission — pinned files are not listed either", async () => {
+  const f = facts({ visibleChannelIds: null });
+  f.channels.set("C-PRIVATE-NOT-MINE", { id: "C-PRIVATE-NOT-MINE", kind: "PRIVATE", name: "board" });
+  const io = fakeIo({ "file.listComments": () => okFrame({ comments: [
+    { id: "fc1", authorId: THEM, authorName: "Casey", body: "@Isla thoughts?" },
+  ] }) });
+  const c = classifyEvent(ev({
+    family: "file", kind: "comment", entity_id: "FK-1",
+    payload: { actor: THEM, channelId: "C-PRIVATE-NOT-MINE", fileKey: "FK-1", body: "@Isla thoughts?", mentions: [ME] },
+  }));
+  await hydrate({ candidate: c, verdict: { surface: "chatFile", reason: "mention" }, facts: f, io });
+  assert.equal(io.calls.some((k) => k.method === "file.listPinned"), false);
+});
+
+// ---------------------------------------------------------------------------
+// approval / escalation / handoff / calendar
+// ---------------------------------------------------------------------------
+
+test("an approval carries the thread of the item it is an approval OF", async () => {
+  const f = facts({
+    approvals: new Map([["A-1", { id: "A-1", status: "pending", requester: THEM, actionClass: "financial", itemId: "T-9" }]]),
+    tasks: new Map([["T-9", { id: "T-9", title: "Wire the retainer", col: "doing", priority: 1 }]]),
+  });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Casey", body: "legal cleared this on Tuesday" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-1", payload: { actor: THEM, requester: THEM, itemId: "T-9", actionClass: "financial" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "approval", reason: "approver" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Board item "Wire the retainer" — doing · priority 1/);
+  assert.match(h.threadContext, /legal cleared this on Tuesday/);
+});
+
+test("an approval on a DECISION falls back to the decision thread, and only then", async () => {
+  const f = facts({ approvals: new Map([["A-2", { id: "A-2", status: "pending", requester: THEM, itemId: "D-7" }]]) });
+  const io = fakeIo({
+    "decision.listComments": () => okFrame({ comments: [{ id: "c1", authorName: "Casey", body: "we ruled out the cheaper vendor" }] }),
+  });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-2", payload: { actor: THEM, requester: THEM, itemId: "D-7" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "approval", reason: "approver" }, facts: f, io });
+
+  assert.match(h.threadContext, /we ruled out the cheaper vendor/);
+  assert.equal(io.calls.filter((k) => k.method === "board.taskComments").length, 1, "board is tried first, once");
+});
+
+test("an approval whose board thread is EMPTY does not pay for a second probe", async () => {
+  const f = facts({ approvals: new Map([["A-3", { id: "A-3", status: "pending", requester: THEM, itemId: "T-8" }]]) });
+  const io = fakeIo({ "board.taskComments": () => okFrame({ comments: [] }) });
+  const c = classifyEvent(ev({ family: "approval", kind: "approval.requested", entity_id: "A-3", payload: { actor: THEM, requester: THEM, itemId: "T-8" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "approval", reason: "approver" }, facts: f, io });
+
+  assert.equal(h.threadContext, null);
+  assert.equal(io.calls.some((k) => k.method === "decision.listComments"), false, "an empty thread is an answer, not a refusal");
+});
+
+test("an escalation carries the escalated task's row and its comments", async () => {
+  const f = facts({
+    escalations: new Map([["E-1", { id: "E-1", title: "Blocked on credentials", severity: "high", taskId: "T-5" }]]),
+    tasks: new Map([["T-5", { id: "T-5", title: "Migrate the vault", col: "blocked", priority: 0 }]]),
+  });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [{ id: "c1", authorName: "Casey", body: "the rotation script needs an admin key" }] }),
+  });
+  const c = classifyEvent(ev({ family: "escalation", kind: "escalation.created", entity_id: "E-1", payload: { actor: THEM, taskId: "T-5", severity: "high" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "escalation", reason: "assignee" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Board item "Migrate the vault" — blocked · priority 0/);
+  assert.match(h.threadContext, /needs an admin key/);
+});
+
+test("an escalation whose task thread is unreadable still hydrates", async () => {
+  const f = facts({ escalations: new Map([["E-2", { id: "E-2", title: "Stuck", severity: "low", taskId: "T-6" }]]) });
+  const io = fakeIo({});
+  const c = classifyEvent(ev({ family: "escalation", kind: "escalation.created", entity_id: "E-2", payload: { actor: THEM, taskId: "T-6" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "escalation", reason: "assignee" }, facts: f, io });
+  assert.equal(h.ok, true);
+  assert.equal(h.threadContext, null);
+});
+
+test("a handoff carries the originating task's thread", async () => {
+  const f = facts({ tasks: new Map([["T-7", { id: "T-7", title: "Draft the board pack", col: "doing", detail: "for Thursday" }]]) });
+  const io = fakeIo({
+    "board.taskComments": () => okFrame({ comments: [
+      { id: "c1", authorName: "Casey", body: "sections 1-3 are done, 4 needs the latest numbers" },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "handoff", kind: "handoff.offered", entity_id: "R-1", payload: { actor: THEM, to: ME, from: THEM, itemId: "T-7", intent: "take over section 4" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "handoff", reason: "named" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Intent: take over section 4/);
+  assert.match(h.text, /Board item "Draft the board pack" — doing/);
+  assert.match(h.threadContext, /4 needs the latest numbers/);
+});
+
+test("a calendar event carries the room it was agreed in and earlier occurrences", async () => {
+  const msgs = [{ id: "m1", authorId: THEM, authorName: "Casey", body: "let's move the weekly to Thursdays", createdAt: "2026-08-10T09:00:00.000Z" }];
+  const f = facts({
+    visibleChannelIds: new Set(["C-ops"]),
+    myEvents: new Map([
+      ["E-now", { id: "E-now", title: "Ops weekly", startsAt: "2026-08-13T09:00:00.000Z", channelId: "C-ops" }],
+      ["E-old", { id: "E-old", title: "Ops weekly", startsAt: "2026-08-06T09:00:00.000Z", location: "Room 2" }],
+      ["E-other", { id: "E-other", title: "Board review", startsAt: "2026-08-05T09:00:00.000Z" }],
+    ]),
+  });
+  f.channels.set("C-ops", { id: "C-ops", kind: "PUBLIC", name: "ops" });
+  f.channelPages.set("C-ops", { byId: new Map(msgs.map((m) => [m.id, m])), messages: msgs });
+  const io = fakeIo({});
+  const c = classifyEvent(ev({ family: "calendar", kind: "event.rescheduled", entity_id: "E-now", payload: { actor: THEM, channelId: "C-ops", title: "Ops weekly" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "calendar", reason: "attendee" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.threadContext, /move the weekly to Thursdays/);
+  assert.match(h.threadContext, /Earlier in this series:/);
+  assert.match(h.threadContext, /2026-08-06T09:00:00.000Z · Room 2/);
+  assert.doesNotMatch(h.threadContext, /Board review/, "a different meeting is not this series");
+});
+
+test("a calendar event with no room and no series carries no invented context", async () => {
+  const f = facts({ myEvents: new Map([["E-1", { id: "E-1", title: "1:1", startsAt: "2026-08-13T09:00:00.000Z" }]]) });
+  const io = fakeIo({});
+  const c = classifyEvent(ev({ family: "calendar", kind: "event.created", entity_id: "E-1", payload: { actor: THEM, calendarMemberId: ME, title: "1:1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "calendar", reason: "owner" }, facts: f, io });
+  assert.equal(h.ok, true);
+  assert.equal(h.threadContext, null);
+  assert.equal(io.calls.length, 0);
+});
+
+// ---------------------------------------------------------------------------
+// artifact bodies — the agent must have READ the thing it is commenting on
+// ---------------------------------------------------------------------------
+
+test("a doc comment carries the document body, bounded", async () => {
+  const f = facts({ fileAcl: new Map([["F-2", { ownerId: ME, shared: true, name: "Pricing memo", kind: "DOC" }]]) });
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "is the tier-two number right?" }] }),
+    "files.docRead": () => okFrame({ html: `<h1>Pricing memo</h1><p>Tier two is ${"$"}4,800 per seat.</p>` }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-2", payload: { actor: THEM, name: "Pricing memo", commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Document:/);
+  assert.match(h.text, /Tier two is \$4,800 per seat\./);
+  assert.match(h.text, /is the tier-two number right\?/);
+  assert.doesNotMatch(h.text, /<p>/, "markup must not reach the model");
+});
+
+test("a doc body that is too long is clipped, and the comment still survives", async () => {
+  const f = facts({ fileAcl: new Map([["F-3", { ownerId: ME, shared: true, name: "Long", kind: "DOC" }]]) });
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "THE QUESTION" }] }),
+    "files.docRead": () => okFrame({ html: `<p>${"w".repeat(20000)}</p>` }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-3", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.ok(h.text.length < 6000, `doc body was not bounded (${h.text.length} chars)`);
+  assert.match(h.text, /THE QUESTION/, "the comment being answered must survive the doc body");
+});
+
+test("clampDocHtml bounds what a pull holds and converts", () => {
+  // files.docRead has no `limit` on the wire (ui-parity documents `{ fileId }`),
+  // so the only place this can be bounded is the instant it lands — before
+  // htmlToText walks it and before the per-pull cache keeps it. Measured before
+  // the clamp: 8 MB of HTML → 7,435,349 characters converted to retain 4,000.
+  assert.equal(clampDocHtml("<p>short</p>"), "<p>short</p>");
+  assert.equal(clampDocHtml("x".repeat(DOC_HTML_MAX_CHARS + 10)).length, DOC_HTML_MAX_CHARS);
+  assert.equal(clampDocHtml(null), "");
+  assert.ok(DOC_HTML_MAX_CHARS > 4000, "the clamp must leave room for a full text budget after markup");
+});
+
+test("a HUGE doc is clamped before it is converted, and never exceeds the shared ceiling", async () => {
+  // Two separate bounds, and the second one used to be missing entirely.
+  //   1. the raw HTML is sliced the instant it lands, so an 8 MB document does
+  //      not walk 7.4 M characters through htmlToText to retain 4,000;
+  //   2. the JOINED text is clipped like every other surface's — hydrateDoc had
+  //      dropped its outer clip(), making it the one hydrator that could hand
+  //      `item.content` more than the shared clamp allows.
+  // The name is unbounded on the wire (it rides `c.ids.name` / the ACL row), so
+  // it is the part that proves the OUTER clip is doing work rather than sitting
+  // above a ceiling the parts can never reach.
+  const f = facts({ fileAcl: new Map([["F-BIG", { ownerId: ME, shared: true, name: "N".repeat(50_000), kind: "DOC" }]]) });
+  const huge = `<p>${"w".repeat(2_000_000)}</p>`;
+  const io = fakeIo({
+    "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "z".repeat(9000) }] }),
+    "files.docRead": () => okFrame({ html: huge }),
+  });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-BIG", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.ok(h.text.length <= 5601, `hydrateDoc must honour its declared ceiling (${h.text.length} chars)`);
+});
+
+test("a SHEET is never asked for a doc body — hq would only refuse", async () => {
+  const f = facts({ fileAcl: new Map([["F-4", { ownerId: ME, shared: true, name: "Model", kind: "SHEET" }]]) });
+  const io = fakeIo({ "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "row 12?" }] }) });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-4", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.equal(io.calls.some((k) => k.method === "files.docRead"), false);
+});
+
+test("an unreadable doc body leaves the comment thread intact", async () => {
+  const f = facts({ fileAcl: new Map([["F-5", { ownerId: ME, shared: true, name: "Memo", kind: "DOC" }]]) });
+  const io = fakeIo({ "files.comments": () => okFrame({ comments: [{ id: "k1", authorName: "Casey", body: "thoughts?" }] }) });
+  const c = classifyEvent(ev({ family: "files", kind: "doc.comment", entity_id: "F-5", payload: { actor: THEM, commentId: "k1" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "doc_comment", reason: "owner" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /thoughts\?/);
+  assert.doesNotMatch(h.text, /Document:/);
+});
+
+test("a file comment names the file — type and size, not just an opaque key", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  f.channels.set("C-eng", { id: "C-eng", kind: "PUBLIC", name: "engineering" });
+  const io = fakeIo({
+    "file.listComments": () => okFrame({ comments: [{ id: "fc1", authorName: "Casey", body: "page 3 is stale" }] }),
+    "file.listPinned": () => okFrame({ files: [
+      { id: "pf1", fileKey: "fk-1", name: "q3-forecast.pdf", mimeType: "application/pdf", sizeBytes: 1258291 },
+    ] }),
+  });
+  const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc1", payload: { actor: THEM, fileKey: "fk-1", channelId: "C-eng" } }));
+  const h = await hydrate({ candidate: c, verdict: { surface: "file_comment", reason: "member" }, facts: f, io });
+
+  assert.equal(h.ok, true);
+  assert.match(h.text, /Comment on file q3-forecast\.pdf/);
+  assert.match(h.text, /File: q3-forecast\.pdf · application\/pdf · 1\.2 MB/);
+  assert.match(h.text, /page 3 is stale/);
+  assert.equal(h.subjectDetail, "q3-forecast.pdf");
+});
+
+test("a file in a room outside my roster is never asked about", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-mine"]) });
+  const io = fakeIo({ "file.listComments": () => okFrame({ comments: [{ id: "fc1", authorName: "Casey", body: "x" }] }) });
+  const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: "fc1", payload: { actor: THEM, fileKey: "fk-2", channelId: "C-not-mine" } }));
+  await hydrate({ candidate: c, verdict: { surface: "file_comment", reason: "member" }, facts: f, io });
+  assert.equal(io.calls.some((k) => k.method === "file.listPinned"), false);
+});
+
+test("two comments on files in ONE room share a single listPinned read", async () => {
+  const f = facts({ visibleChannelIds: new Set(["C-eng"]) });
+  const io = fakeIo({
+    "file.listComments": () => okFrame({ comments: [{ id: "fc1", authorName: "Casey", body: "x" }] }),
+    "file.listPinned": () => okFrame({ files: [] }),
+  });
+  const cache = new Map();
+  for (const key of ["fk-a", "fk-b"]) {
+    const c = classifyEvent(ev({ family: "file", kind: "file.commented", entity_id: `c-${key}`, payload: { actor: THEM, fileKey: key, channelId: "C-eng" } }));
+    await hydrate({ candidate: c, verdict: { surface: "file_comment", reason: "member" }, facts: f, io, cache });
+  }
+  assert.equal(io.calls.filter((k) => k.method === "file.listPinned").length, 1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cohortapp/agent-sdk",
-  "version": "2.15.0",
+  "version": "2.17.0",
   "description": "Cohort Agent SDK — autonomous AI colleague runtime. Deploy senior AI colleagues on dedicated Mac minis, wired to the Cohort operating surface.",
   "type": "module",
   "bin": {
@@ -18,6 +18,8 @@
     "./singleton": "./lib/singleton.js",
     "./cadence-bus": "./lib/cadence-bus.mjs",
     "./fs-atomic": "./lib/fs-atomic.mjs",
+    "./context/budget": "./lib/context/budget.mjs",
+    "./context/history-scope": "./lib/context/history-scope.mjs",
     "./org/protocol": "./lib/org/protocol.mjs",
     "./org/client": "./lib/org/client.mjs",
     "./org/ui-parity": "./lib/org/ui-parity.mjs",

package/plugins/maestro-skills/skills/inbound-triage.md

@@ -1,13 +1,13 @@
 ---
 name: inbound-triage
-description: Decide, for each inbound Cohort event, whether to answer in this turn, acknowledge and file it on the board and run a workflow, or hand it to a peer session — and always acknowledge in the same turn. Use when a feed `inbound` line arrives, when reading `maestro inbox list`, or when you are unsure whether an ask is a reply or a task.
+description: Decide, for each inbound Cohort event, whether to answer in this turn, file it on the board and run a workflow, or hand it to a peer session — and whether the person hears anything before the answer (usually not). Use when a feed `inbound` line arrives, when reading `maestro inbox list`, or when you are unsure whether an ask is a reply or a task.
 ---
 
 # Inbound triage
 
-Every inbound event is one of three things. Decide in the first turn, and say
-something to the person in that same turn — a person who asked gets a reply
-or an acknowledgement before you do anything else.
+Every inbound event is one of three things. Decide in the first turn. Whether
+you SAY anything in that turn is a separate question, and the default answer is
+no: see "The one-interim rule" at the foot of this skill.
 
 ## The three outcomes
 
@@ -17,12 +17,10 @@ or an acknowledgement before you do anything else.
    --text "…"` → `maestro inbox done <id>`. No board row: the ledger on the
    server already records that you answered.
 
-2. **Acknowledge, file, work here.** The ask needs real work — reading,
-   drafting, building, several steps — but you can finish it in this session
-   inside an hour or two without blocking the front door. In ONE turn:
+2. **File it, work here.** The ask needs real work — reading, drafting,
+   building, several steps — but you can finish it in this session inside an
+   hour or two without blocking the front door. In ONE turn:
    - `maestro inbox claim <id>`
-   - `maestro inbox reply <id> --text "On it — I'll have <X> to you by <when>."`
-     (specific deliverable, specific time; never "I'll look into it")
    - `maestro board track <id> --stage accepted --title "<what you took on>"
      --why "<one line: why this is more than a reply>"`
    - then run the work — a `Workflow` when it has distinct steps, plain tool
@@ -34,10 +32,10 @@ or an acknowledgement before you do anything else.
      (or `messaging_send` to the thread), then `maestro board track <id>
      --stage done` and `maestro inbox done <id>`.
 
-3. **Acknowledge, file, hand to a peer.** Same as 2, but the work is long
-   (hours), heavy (a repo build, a large research pass), or would block you
-   from answering the next person. After the acknowledgement and the
-   `--stage accepted` track, `maestro session spawn --name <slug> "<prompt>"`
+3. **File it, hand to a peer.** Same as 2, but the work is long (hours), heavy
+   (a repo build, a large research pass), or would block you from answering the
+   next person. After the `--stage accepted` track — and, if the ask is big
+   enough to warrant one, the plan (below) — `maestro session spawn --name <slug> "<prompt>"`
    with a prompt that names the deliverable, the channel and thread to report
    to, the inbox id, and the instruction to `SendMessage` you a two-line
    status when done. You stay the one who talks to the human; the peer talks to
@@ -54,14 +52,14 @@ or an acknowledgement before you do anything else.
   space's board. You do not choose the board.
 - Will it take longer than the next inbound can wait? → peer.
 - Is it a question you should not answer alone (a commitment, spend, an
-  external promise)? → acknowledge, file with `--stage blocked` and `notify`
-  your principal; do not guess.
+  external promise)? → file with `--stage blocked` and `notify` your principal,
+  and say in-channel what you need and from whom. That is a message with
+  content in it, so it is always worth sending; do not guess.
 
 ## Special topics
 
-- **Calls** (`topic: call`): acknowledge in the channel and either join if
-  you are free now or propose a time; the media stays with the avatar service,
-  you do not handle audio here.
+- **Calls** (`topic: call`): answer in the channel — join if you are free now,
+  or propose a time. Either is a real answer, not an acknowledgement.
 - **Comments on files/boards**: reply in the thread of the comment, not in a
   DM; a comment that asks for a change to a document is outcome 2.
 - **Inbound email** (`surface: email`): the same three outcomes; reply through
@@ -71,10 +69,40 @@ or an acknowledgement before you do anything else.
   the same message re-delivered after a crash — check the thread before you
   answer twice.
 
-## The same-turn rule
+## The one-interim rule
 
-Whatever the outcome, the person hears from you in the turn the event
-arrived. An acknowledgement is one or two sentences with a concrete next step
-and time. Do not open with filler and do not describe how you work — say what
-they will get and when. The persona rules (`persona-discipline`) apply to the
-acknowledgement too.
+~~"Whatever the outcome, the person hears from you in the turn the event
+arrived."~~ — struck 2026-09-12. Measured over fourteen days in
+`org_default_adaptic`: of 10,667 agent messages, 3,069 (28.8 %) were opening
+acknowledgements and 961 (9.0 %) were progress nags, and 272 of those
+acknowledgements were never followed by a substantive reply inside an hour.
+Agent-to-human volume went from 2:1 to 158:1 in a fortnight, 80 % of it into one
+channel.
+
+**Silence is the default. A message before the answer is never a reflex; it is
+either absent or it is a plan.**
+
+- **Outcome 1 (reply now):** the reply IS the acknowledgement. Nothing before it.
+- **Outcome 2 or 3, ordinary size:** say nothing. Claim it, file it, do it, and
+  let the result be the first thing they read. A person who has been waiting two
+  minutes has lost nothing; a person who got "On it" and then nothing for an
+  hour has lost their trust in you.
+- **Outcome 2 or 3, large enough that the shape matters** (a workflow, a peer
+  team, a multi-day research pass, anything where the approach is itself a
+  decision): post the PLAN, once, as the first step of doing the work — what you
+  will do, in what order, and what comes back. Three bullets at most, in your own
+  words about this specific ask.
+- **Never** a generic opener. `On it`, `Looking into it`, `Checking`, `One
+  moment`, `Got it`, `Will do`, `Working on it`, `Taking a look`, `Digging in`:
+  the daemon's sanitiser now refuses every one of these outright, and so should
+  you.
+- **Never** a promise you have no mechanism to keep. "I'll come back as soon as
+  I've got something" is only sayable because the obligation ledger will in fact
+  chase it; do not say it about work that has no such ledger behind it.
+- **At most one** such message per channel per fifteen minutes, whatever else is
+  in flight there. If a teammate or the daemon has already spoken in that room
+  inside the window, you have had your turn.
+
+The persona rules (`persona-discipline`) apply to a plan exactly as to a reply.
+The daemon's half of the same policy — tiers, the room budget, the sanitiser —
+is `docs/guides/poller-daemon-setup.md` §2.6a.

package/plugins/maestro-skills/skills/main-session.md

@@ -43,8 +43,9 @@ Each line is a JSON object with a `type`. Handle it in the turn it arrives.
 
 - `inbound` — `{id, surface, topic, from, channelId, threadId, preview, path}`.
   `maestro inbox show <id>` for the full item, then follow the
-  `inbound-triage` skill: reply now, or acknowledge + `maestro board track
-  <id> --stage accepted` + work it, or spawn a peer. Claim it first
+  `inbound-triage` skill: reply now, or `maestro board track <id> --stage
+  accepted` + work it, or spawn a peer. Saying something BEFORE the answer is
+  the exception, not the rule — see that skill's one-interim rule. Claim it first
   (`maestro inbox claim <id>`) so the daemon's sweep does not re-deliver it,
   reply with `maestro inbox reply <id> --text "…"`, and close with
   `maestro inbox done <id>`. The reply command is the reply lane: it runs the
@@ -67,8 +68,9 @@ Each line is a JSON object with a `type`. Handle it in the turn it arrives.
   disk.
 
 Do not batch: an inbound line that sits while you finish something else is a
-person waiting. Acknowledge in the same turn (see `inbound-triage`), then
-finish the other thing.
+person waiting. DECIDE it in the turn it arrives (see `inbound-triage`) — claim
+it, file it, start it — then finish the other thing. Deciding in the same turn
+is the rule; speaking in the same turn is not.
 
 ## The idle loop