@cohortapp/agent-sdk 2.15.0 → 2.17.0

package/.env.example

@@ -226,6 +226,9 @@ GREPTILE_API_KEY=
 # Flags that control system behaviour. These are not secrets.
 #
 
-# Enable session context compiler for optimised daemon prompts
-# Set to 1 to pre-compile context before each Claude Code session (recommended)
+# The session context compiler: pre-compile context before each Claude Code
+# session. ON BY DEFAULT in code as well as here — the two used to disagree
+# (code read `=== "1"`, this file shipped `=1`), so which of two materially
+# different context paths ran depended on whether the operator had copied this
+# file. Set to 0 only to fall back to the legacy path in a hurry.
 DAEMON_CONTEXT_COMPILER=1

package/docs/guides/front-door-session.md

@@ -265,11 +265,22 @@ Each line from the feed is one unit of work. The policy the session follows
 1. **Answer in the turn** when the ask is answerable in one reply from what
    the agent already knows. `maestro inbox reply <id>` routes through the same
    send-gate and audit as every other outbound path.
-2. Otherwise **acknowledge in-channel in the same turn**, file the ask on the
-   conversation's board (`maestro board track <inbox-id> --stage accepted
-   --title … --why …`), and either run the work as a dynamic workflow inside
-   the session or spawn a peer (`maestro session spawn --name <slug> "<prompt>"`).
-   Report back in-channel and `board track --stage done` on completion.
+2. Otherwise **say nothing yet** — file the ask on the conversation's board
+   (`maestro board track <inbox-id> --stage accepted --title … --why …`) and
+   either run the work as a dynamic workflow inside the session or spawn a peer
+   (`maestro session spawn --name <slug> "<prompt>"`). Report back in-channel
+   and `board track --stage done` on completion.
+
+   ~~"Otherwise **acknowledge in-channel in the same turn**"~~ — struck
+   2026-09-12. That reflex was 28.8 % of every message this fleet sent, and 9 %
+   of it was never followed by a substantive reply at all. The daemon's
+   assurance sweep owns the ONE interim an ask may earn: nothing for the first
+   90 s, then at most one line, and at most one line per channel per 15 minutes
+   FROM THIS SEAT however many asks are in flight there — the budget is durable
+   under this agent's `AGENT_DIR`, and seats share no store
+   (`docs/guides/poller-daemon-setup.md` §2.6a). If the work is big enough that the human needs to know its shape,
+   post the PLAN — what you will do, in what order, what comes back — as the
+   first step of doing it, not as a promise in front of it.
 3. **Handoffs** (`{"type":"handoff", …}`) are cadence ticks the daemon has
    handed over; the session runs the rendered prompt and `maestro session ack
    <tickId>`. A handoff not acked within 30 minutes is re-enqueued by the

package/docs/guides/poller-daemon-setup.md

@@ -203,7 +203,55 @@ Handles quick replies without spawning a full Claude session:
 
 - `isQuickReply()` detects items that can be answered immediately (greetings, acknowledgments)
 - `sendQuickResponse()` sends a fast reply via the appropriate channel
-- `sendHoldingMessage()` sends "Got it, working on this" for complex requests
+- `sendHoldingMessage()` composes the one-line interim, when one is owed at all
+
+### 2.6a Acknowledgement discipline (`assurance.mjs` + `lib/assurance/`)
+
+**Silence is the default.** ~~"`sendHoldingMessage()` sends 'Got it, working on
+this' for complex requests."~~ — 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 timed progress nags — 37.8 % carrying no
+content — and 272 of those acknowledgements were never followed by a substantive
+reply inside an hour. Nothing is sent when an obligation opens any more.
+
+What governs an interim now:
+
+| Gate | Rule |
+|---|---|
+| **Tier** (`lib/assurance/tier.mjs`) | `answer` ⇒ never anything (the reply is the acknowledgement). `work` ⇒ nothing for `ACK_AFTER_MS`, then at most one. `plan` ⇒ one message, and it is the plan. **The plan tier currently degrades to the work path.** `assurance.notePlan` needs the session's first assistant turn, and `dispatcher.mjs` spawns with `--output-format json`, so stdout arrives as one object at exit — after the answer. Streaming it is a dispatcher change and lands with WP-2; until then a plan-tier ask gets the same single interim as a work-tier one, never silence. |
+| **Time** (`ASSURANCE_ACK_AFTER_MS`, 90 s) | Below it the typing indicator is the acknowledgement. |
+| **Room** (`lib/assurance/room-budget.mjs`, `ASSURANCE_ROOM_INTERIM_WINDOW_MS`, 15 min) | At most ONE interim per `(service, channel)` per window **per seat**, however many obligations are open in it. Over budget ⇒ the debt is still opened and tracked; only the message is withheld. Durable at `state/obligations/room-budget.json`, which is under `AGENT_DIR` — seats share no store, so a room with N seats in it has a ceiling of N per window, not one. This gate is the backstop on what survives the three above it, not the thing that removed the measured traffic. |
+| **Once** | `interimSaid` latches per obligation and is INHERITED by a retry that reopens the same key. |
+| **Copy** | `sanitiseAckText` rejects the generic openers the ack prompt already forbade (`on it`, `looking into`, `checking`, `one moment`, `got it`, `will do`, `working on it`, `taking a look`, `digging in`) and anything under 20 characters. Rejection ⇒ null ⇒ send nothing. **That list is a floor, not the policy** — it is a phrase blocklist sized against the measured population, and "Picking this up now." is just as empty and passes it. Widen it when a new phrasing is measured in production; do not read a gap in it as permission. |
+
+**There are no timed progress updates.** `composeProgress`,
+`ASSURANCE_PROGRESS_AFTER_MS`, `ASSURANCE_PROGRESS_EVERY_MS` and
+`ASSURANCE_PROGRESS_MAX` are deleted. A message that is a pure function of
+elapsed minutes tells a reader nothing the timestamp does not, and two
+per-obligation timers over overlapping work put "Still on this — 5 minutes in"
+beside "Still going — 15 minutes in" at the same instant in a live channel. Long
+work either reports CONTENT — `lib/assurance/plan-note.mjs` renders at most
+three bullets of the session's OWN stated intent, or returns null and nothing is
+posted — or it stays quiet until the answer.
+
+**Outcome notices are unaffected by the room budget** — suppressing one
+re-creates the original bug, a person never told their work died. They are
+deduplicated twice instead, on questions the interim budget does not ask:
+
+- **once per `(channel, obligationKey, notice)`** (`assurance.noticeAlreadySaid`,
+  inherited across a retry that reopens the same key) — this is the retry loop:
+  notice → retry → fresh record → notice again;
+- **once per `(room, notice, exact sentence)`** (`room-budget.claimRoomNotice`)
+  — this is the SIBLING case the first cannot reach. Twenty separate asks in one
+  channel whose sessions all die the same way are twenty separate records, and
+  the stale sentence says nothing about which ask it is, so the reader gets one
+  line twenty times and cannot tell them apart.
+
+Only a BYTE-IDENTICAL repeat is withheld. A different cause, a different
+excerpt, "a retry is running" versus "I have stopped" — all distinct text, all
+said, at any volume. The needs-attention escalation is written per obligation
+regardless, so an operator still sees every dead ask even when the room only
+heard about the first.
 
 ### 2.7 Session Lock (`session-lock.mjs`)
 
@@ -231,7 +279,10 @@ Pre-compiles session context to reduce prompt size:
 
 - Reads recent interactions, queue state, and active items
 - Compresses context to fit within token limits
-- Enabled via `DAEMON_CONTEXT_COMPILER=1` in `.env`
+- **On by default.** Set `DAEMON_CONTEXT_COMPILER=0` in `.env` to fall back to
+  the legacy per-prompt history path. The code used to default this OFF while
+  `.env.example` shipped `=1`, so which path ran depended on whether the
+  operator had copied the example env; both now agree.
 
 ---
 

package/lib/assurance/plan-note.mjs

@@ -0,0 +1,251 @@
+/**
+ * lib/assurance/plan-note.mjs — the only interim that is allowed to exist,
+ * and the copy rules that govern every interim.
+ *
+ * WHY A PLAN AND NOT A HOLDING LINE
+ *
+ * The research is unambiguous and it does not say what the old code assumed.
+ * Nielsen: under a second, show nothing; under ten, a state change rather than
+ * a message; beyond ten, show WORK. The labour-illusion result is about showing
+ * work, not about promising to return — and every source agrees that the broken
+ * promise is what destroys trust. Production bore that out precisely: of 3,069
+ * opening acknowledgements, 272 were never followed by a substantive reply
+ * within the hour.
+ *
+ * So the replaced mechanism is not "a better ack". It is: when the work is big
+ * enough that a human deserves to hear something before the answer, the one
+ * thing they hear is the PLAN the model itself stated — what will be done, in
+ * what order — rendered from the session's own first turn.
+ *
+ * THE HARD RULE: NEVER FABRICATE A PLAN.
+ *
+ * Every bullet is text the model wrote. Markers are normalised and long lines
+ * are clipped; nothing is invented, summarised into something unsaid, or filled
+ * in from a template. No first turn, or a first turn that states no intent,
+ * returns `null` — and null means the agent posts NOTHING. A rendered template
+ * over an absent session would be the same content-free message this work
+ * package exists to delete, only longer.
+ *
+ * WHY THE COPY RULES LIVE HERE
+ *
+ * After `composeProgress` was deleted, this is the only module left that
+ * COMPOSES interim copy. Two rules apply to every interim the system can emit,
+ * so they live with the composer rather than in two drifting copies:
+ *
+ *   GENERIC_OPENER   — the set the ack system prompt already forbade and the
+ *                      sanitiser did not enforce; 3,069 of them shipped.
+ *                      `assurance.sanitiseAckText` imports this, so the prompt
+ *                      and the filter cannot disagree again.
+ *
+ *                      IT IS A FLOOR, NOT A DEFINITION OF "CONTENT-FREE".
+ *                      This is a phrase blocklist, and a phrase blocklist can
+ *                      only refuse phrasings someone has written down. It
+ *                      refuses every opener in the measured population, which
+ *                      is what it was sized against; "Picking this up now.",
+ *                      "Beginning work on this now." and "Ack — starting on
+ *                      it." are all just as empty and all pass it. That is
+ *                      tolerable ONLY because the blocklist is the last and
+ *                      weakest of four gates, not the policy: the tier decides
+ *                      whether an interim may exist at all, nothing is said
+ *                      before ACK_AFTER_MS, `interimSaid` latches one per ask,
+ *                      the room budget bounds the seat, and two rejected
+ *                      generations latch `ackSuppressed` permanently. A line
+ *                      that slips through is ONE line. Widen the set when a
+ *                      new phrasing is measured in production — do not treat
+ *                      the absence of a phrasing here as permission.
+ *   FORWARD_PROMISE  — "I'll come back", "I'll follow up", "as soon as". A
+ *                      promise is only permissible when a durable obligation
+ *                      exists and the sweep can close it; a plan bullet carries
+ *                      no such backing, so a bullet that is only a promise is
+ *                      dropped.
+ *
+ * PURE. No clock, no disk, no environment, no network.
+ *
+ * @module lib/assurance/plan-note
+ */
+
+"use strict";
+
+/** At most three. A fourth step is a document, not a message. */
+export const PLAN_MAX_BULLETS = 3;
+
+/** Longest a single bullet may be before it is clipped. */
+export const PLAN_BULLET_MAX_CHARS = 160;
+
+/** Shortest a line may be and still be a step rather than a noise. */
+const PLAN_BULLET_MIN_CHARS = 15;
+
+/**
+ * The generic openers the ack system prompt bans ("Never a generic 'on it' or
+ * 'looking into it'") and which shipped 3,069 times because nothing enforced
+ * it. Anchored at the start: a line that OPENS this way is a reflex whatever
+ * follows it.
+ */
+export const GENERIC_OPENER =
+  /^(on it|looking (now|into)|checking|one moment|got it|will do|working on it|taking a look|digging in)\b/i;
+
+/**
+ * A commitment to come back later. Permitted only where a durable obligation
+ * backs it and the sweep can discharge it — which a plan bullet never is.
+ */
+export const FORWARD_PROMISE =
+  /\b(i'?(ll|m going to)\s+(come back|follow up|get back|circle back|report back|update you|let you know|revert)|i will\s+(come back|follow up|get back|circle back|report back|update you|let you know|revert)|as soon as|the moment it'?s done)\b/i;
+
+/** @param {unknown} text @returns {boolean} */
+export function containsForwardPromise(text) {
+  return typeof text === "string" && FORWARD_PROMISE.test(text);
+}
+
+/** Text blocks out of one assistant message's content array. */
+function textOfContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((b) => b && typeof b === "object" && b.type === "text" && typeof b.text === "string")
+    .map((b) => b.text)
+    .join("\n");
+}
+
+/** One event/object → its assistant text, or "". */
+function textOfEvent(ev) {
+  if (!ev || typeof ev !== "object" || Array.isArray(ev)) return "";
+  if (ev.type === "assistant") {
+    const msg = ev.message && typeof ev.message === "object" ? ev.message : ev;
+    return textOfContent(msg.content).trim();
+  }
+  // The `--output-format json` result object: one field carrying the run's text.
+  if (typeof ev.result === "string") return ev.result.trim();
+  if (ev.message && typeof ev.message === "object") return textOfContent(ev.message.content).trim();
+  return "";
+}
+
+/** Parse, tolerantly. A banner line before the JSON must not lose the payload. */
+function parseLoose(raw) {
+  const t = String(raw).trim();
+  if (!t) return null;
+  try { return JSON.parse(t); } catch { /* fall through to the tolerant paths */ }
+  // Newline-delimited stream-json: take every line that parses.
+  const lines = t.split("\n").map((l) => l.trim()).filter(Boolean);
+  if (lines.length > 1) {
+    const evs = [];
+    for (const l of lines) { try { evs.push(JSON.parse(l)); } catch { /* a prose line is not an event */ } }
+    if (evs.length) return evs;
+  }
+  const start = t.indexOf("{");
+  const end = t.lastIndexOf("}");
+  if (start !== -1 && end > start) {
+    try { return JSON.parse(t.slice(start, end + 1)); } catch { /* genuinely not JSON */ }
+  }
+  return null;
+}
+
+/**
+ * The session's FIRST assistant turn, as plain text — or null.
+ *
+ * First and not last, deliberately: the first turn is where a model states what
+ * it is about to do. The last turn is the answer, and the answer is the
+ * session's to deliver, not this module's to pre-empt.
+ *
+ * @param {unknown} input  raw stdout, a parsed result object, a stream-json
+ *                         event, an array of events, or plain prose
+ * @returns {string|null}
+ */
+export function firstAssistantText(input) {
+  if (input == null) return null;
+
+  if (Array.isArray(input)) {
+    for (const ev of input) {
+      const t = textOfEvent(ev);
+      if (t) return t;
+    }
+    return null;
+  }
+
+  if (typeof input === "object") {
+    const t = textOfEvent(input);
+    return t || null;
+  }
+
+  if (typeof input !== "string") return null;
+  const trimmed = input.trim();
+  if (!trimmed) return null;
+
+  const parsed = parseLoose(trimmed);
+  if (parsed != null) {
+    const t = firstAssistantText(parsed);
+    if (t) return t;
+    // It parsed as JSON but carried no assistant text. Returning the raw JSON
+    // as "prose" would put a serialised object in front of a human.
+    return null;
+  }
+  // It LOOKS like a payload and will not parse — a truncated or corrupt stdout.
+  // Prose never opens with a brace; showing this to a human would be showing
+  // them our own broken plumbing.
+  if (/^[[{]/.test(trimmed)) return null;
+  return trimmed;
+}
+
+/** Strip a list marker without touching the model's words. */
+function stripMarker(line) {
+  return line.replace(/^\s*(?:[-*•–—]|\d{1,2}[.)])\s+/, "").trim();
+}
+
+/**
+ * Does this line STATE an intent?
+ *
+ * Two shapes qualify and nothing else does: an explicit list item, or a
+ * first-person/sequencing opener. A question, an answer, an aside and a
+ * pleasantry all fail, which is why a turn that is not a plan renders nothing.
+ */
+const INTENT_OPENER =
+  /^(i'?ll|i will|i'?m going to|i am going to|i plan to|i'?m starting|first|then|next|after that|finally|start(ing)? by|step \d)\b/i;
+
+function isStatedStep(rawLine) {
+  const line = String(rawLine || "").trim();
+  if (!line) return false;
+  const listItem = /^\s*(?:[-*•–—]|\d{1,2}[.)])\s+/.test(line);
+  const body = stripMarker(line);
+  if (!body) return false;
+  if (body.endsWith("?")) return false;            // a question back is not a plan
+  if (GENERIC_OPENER.test(body)) return false;      // "On it" in a numbered list is still "On it"
+  if (containsForwardPromise(body)) return false;   // no promise without a mechanism
+  if (body.length < PLAN_BULLET_MIN_CHARS) return false;
+  return listItem || INTENT_OPENER.test(body);
+}
+
+function clip(s) {
+  return s.length <= PLAN_BULLET_MAX_CHARS ? s : `${s.slice(0, PLAN_BULLET_MAX_CHARS).trimEnd()}…`;
+}
+
+/**
+ * Render the plan the model stated, or null.
+ *
+ * @param {unknown} firstTurn  whatever the dispatcher can give us of the
+ *                             session's first assistant turn
+ * @returns {string|null}      the message to post, or null ⇒ post nothing
+ */
+export function renderPlanNote(firstTurn) {
+  const text = firstAssistantText(firstTurn);
+  if (!text) return null;
+
+  const bullets = [];
+  for (const line of text.split("\n")) {
+    if (bullets.length >= PLAN_MAX_BULLETS) break;
+    if (!isStatedStep(line)) continue;
+    const body = clip(stripMarker(line));
+    if (!bullets.includes(body)) bullets.push(body);
+  }
+  if (bullets.length === 0) return null;
+
+  return [`Here's the plan:`, ...bullets.map((b) => `- ${b}`)].join("\n");
+}
+
+export default {
+  renderPlanNote,
+  firstAssistantText,
+  containsForwardPromise,
+  PLAN_MAX_BULLETS,
+  PLAN_BULLET_MAX_CHARS,
+  GENERIC_OPENER,
+  FORWARD_PROMISE,
+};

package/lib/assurance/plan-note.test.mjs

@@ -0,0 +1,234 @@
+/**
+ * plan-note.test.mjs — if we say we are working, show work; otherwise say nothing.
+ *
+ * The rule this pins is the hard one: NEVER FABRICATE A PLAN. Every bullet must
+ * be text the model itself wrote in its own first turn. When there is no first
+ * turn, or nothing in it that states an intent, the answer is null and null
+ * means the agent posts nothing at all. A rendered template over an absent
+ * session is exactly the content-free message this whole work package exists to
+ * delete — it would merely be a longer one.
+ *
+ * Run: node --test lib/assurance/plan-note.test.mjs
+ */
+
+import { test, describe } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  renderPlanNote,
+  firstAssistantText,
+  PLAN_MAX_BULLETS,
+  FORWARD_PROMISE,
+  containsForwardPromise,
+} from "./plan-note.mjs";
+
+const STEPS = [
+  "First I'll pull the July ledger rows and the forecast we signed off in June.",
+  "Then I'll reconcile them line by line and mark every variance over 5%.",
+  "Finally I'll write up the three biggest gaps with the numbers behind each.",
+].join("\n");
+
+// ---------------------------------------------------------------------------
+// firstAssistantText — every shape the CLI can hand us
+// ---------------------------------------------------------------------------
+
+describe("firstAssistantText — reading the session's own first turn", () => {
+  test("a --output-format json result object", () => {
+    assert.match(firstAssistantText(JSON.stringify({ type: "result", result: STEPS })), /pull the July ledger/);
+  });
+
+  test("an already-parsed result object", () => {
+    assert.match(firstAssistantText({ type: "result", result: STEPS }), /pull the July ledger/);
+  });
+
+  test("a stream-json assistant message", () => {
+    const msg = { type: "assistant", message: { content: [{ type: "text", text: STEPS }] } };
+    assert.match(firstAssistantText(msg), /pull the July ledger/);
+  });
+
+  test("an array of stream-json events takes the FIRST assistant turn, not the last", () => {
+    const events = [
+      { type: "system", subtype: "init" },
+      { type: "assistant", message: { content: [{ type: "text", text: STEPS }] } },
+      { type: "assistant", message: { content: [{ type: "text", text: "Done — all three variances written up." }] } },
+    ];
+    assert.match(firstAssistantText(events), /pull the July ledger/);
+    assert.doesNotMatch(firstAssistantText(events), /Done —/);
+  });
+
+  test("newline-delimited stream-json text", () => {
+    const ndjson = [
+      JSON.stringify({ type: "system", subtype: "init" }),
+      JSON.stringify({ type: "assistant", message: { content: [{ type: "text", text: STEPS }] } }),
+    ].join("\n");
+    assert.match(firstAssistantText(ndjson), /pull the July ledger/);
+  });
+
+  test("a tool_use block is not text and is skipped", () => {
+    const msg = { type: "assistant", message: { content: [{ type: "tool_use", name: "Read", input: {} }, { type: "text", text: STEPS }] } };
+    assert.match(firstAssistantText(msg), /pull the July ledger/);
+  });
+
+  test("plain prose is taken as itself", () => {
+    assert.equal(firstAssistantText(STEPS), STEPS);
+  });
+
+  test("absent, empty and malformed input read as nothing", () => {
+    for (const bad of [null, undefined, "", "   ", 12, [], {}, { type: "result" }, "{not json", { type: "assistant", message: null }]) {
+      assert.equal(firstAssistantText(bad), null, `${JSON.stringify(bad)} must read as nothing`);
+    }
+  });
+});
+
+// ---------------------------------------------------------------------------
+// renderPlanNote
+// ---------------------------------------------------------------------------
+
+describe("renderPlanNote — at most three bullets of STATED intent, or null", () => {
+  test("three stated steps render as three bullets, in the model's own words", () => {
+    const note = renderPlanNote({ type: "assistant", message: { content: [{ type: "text", text: STEPS }] } });
+    assert.ok(note, "a real first turn with real steps must produce a note");
+    const bullets = note.split("\n").filter((l) => l.startsWith("- "));
+    assert.equal(bullets.length, 3);
+    assert.match(bullets[0], /pull the July ledger/);
+    assert.match(bullets[1], /reconcile them line by line/);
+    assert.match(bullets[2], /three biggest gaps/);
+  });
+
+  test("a numbered list is read as steps", () => {
+    const text = "Here's how I'll approach it:\n1. Pull the deal memos from the data room.\n2. Cross-check each against the signed term sheet.\n3. Flag anything the term sheet does not cover.";
+    const note = renderPlanNote(text);
+    assert.equal(note.split("\n").filter((l) => l.startsWith("- ")).length, 3);
+    assert.doesNotMatch(note, /^\s*1\./m, "the list markers are normalised away, not doubled");
+  });
+
+  test("more than three steps are CLIPPED to three, never summarised into something unsaid", () => {
+    const text = ["1. Pull the ledger rows for July.", "2. Reconcile against the forecast.", "3. Mark variances over five percent.", "4. Write the summary.", "5. Post it in the channel."].join("\n");
+    const note = renderPlanNote(text);
+    const bullets = note.split("\n").filter((l) => l.startsWith("- "));
+    assert.equal(bullets.length, PLAN_MAX_BULLETS);
+    assert.match(bullets[0], /Pull the ledger rows/);
+    assert.match(bullets[2], /variances over five percent/);
+  });
+
+  test("NEVER FABRICATE: every bullet is a substring of the model's own turn", () => {
+    const text = "1. Pull the deal memos from the data room.\n2. Cross-check each against the signed term sheet.";
+    const note = renderPlanNote(text);
+    for (const b of note.split("\n").filter((l) => l.startsWith("- "))) {
+      const body = b.slice(2).replace(/\.$/, "");
+      assert.ok(text.includes(body), `"${body}" is not text the model wrote`);
+    }
+  });
+
+  test("no first turn ⇒ null ⇒ nothing is posted", () => {
+    for (const bad of [null, undefined, "", {}, [], "{broken", { type: "result" }]) {
+      assert.equal(renderPlanNote(bad), null, `${JSON.stringify(bad)} must render nothing`);
+    }
+  });
+
+  test("a first turn with no stated intent ⇒ null, not a template", () => {
+    // Chatter, a question back, an answer — none of these is a plan, and
+    // dressing any of them up as one is the fabrication this rule forbids.
+    for (const text of [
+      "Sure, happy to look at that.",
+      "Which quarter did you mean — Q2 or Q3?",
+      "The board call is at 14:00 UK on Thursday.",
+      "Hmm.",
+    ]) {
+      assert.equal(renderPlanNote(text), null, `"${text}" is not a plan`);
+    }
+  });
+
+  test("a single stated step is still a plan", () => {
+    const note = renderPlanNote("I'll reconcile the July ledger against the signed forecast and list every variance over 5%.");
+    assert.ok(note);
+    assert.equal(note.split("\n").filter((l) => l.startsWith("- ")).length, 1);
+  });
+
+  test("a generic opener is not a step and is dropped", () => {
+    // "On it" inside a numbered list is still "On it".
+    const note = renderPlanNote("1. On it.\n2. Looking into this now.\n3. Pull the July ledger rows and reconcile them against the forecast.");
+    assert.ok(note);
+    const bullets = note.split("\n").filter((l) => l.startsWith("- "));
+    assert.equal(bullets.length, 1);
+    assert.match(bullets[0], /July ledger/);
+  });
+
+  test("…and a turn that is ONLY generic openers renders nothing", () => {
+    assert.equal(renderPlanNote("1. On it.\n2. Checking.\n3. One moment."), null);
+  });
+
+  test("the note names no working agent and wears no assistant costume", () => {
+    const note = renderPlanNote(STEPS);
+    assert.doesNotMatch(note, /\b(Odette|Coh|the agent|automation)\b/i);
+    assert.doesNotMatch(note, /^(sure|certainly|absolutely|happy to|of course)\b/i);
+    assert.doesNotMatch(note, /let me know if|here's a comprehensive/i);
+    assert.doesNotMatch(note, /[\u{1F300}-\u{1FAFF}]/u, "no emoji");
+  });
+
+  test("bullets are clipped, so one runaway paragraph cannot become a wall of text", () => {
+    const long = `I'll ${"reconcile every single line of the ledger ".repeat(20)}now.`;
+    const note = renderPlanNote(long);
+    for (const line of note.split("\n")) assert.ok(line.length <= 200, `line of ${line.length} chars is not a bullet`);
+  });
+
+  test("the renderer is pure — same input, same output, input untouched", () => {
+    const events = [{ type: "assistant", message: { content: [{ type: "text", text: STEPS }] } }];
+    const before = JSON.stringify(events);
+    const first = renderPlanNote(events);
+    for (let i = 0; i < 20; i++) assert.equal(renderPlanNote(events), first);
+    assert.equal(JSON.stringify(events), before);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The copy rule the plan shares with every other interim
+// ---------------------------------------------------------------------------
+
+describe("containsForwardPromise — no promise without a mechanism", () => {
+  test("it recognises the promises the production sample was full of", () => {
+    for (const t of [
+      "Still on this — 5 minutes in. I'll come back as soon as I've got something.",
+      "Still going — 15 minutes in. I'll follow up the moment it's done.",
+      "I'll get back to you shortly.",
+      "I will report back as soon as I have it.",
+      "I'll let you know once it's done.",
+      "I'll circle back on this.",
+    ]) {
+      assert.equal(containsForwardPromise(t), true, `"${t}" is a forward promise`);
+    }
+  });
+
+  test("it does not flag a statement of what is being done now", () => {
+    for (const t of [
+      "Pulling the July ledger rows and reconciling them against the forecast.",
+      "I'm reconciling July against the forecast now.",
+      "Three variances so far, all in payroll.",
+      "Done — pushed as a41f0c9.",
+    ]) {
+      assert.equal(containsForwardPromise(t), false, `"${t}" is not a promise`);
+    }
+  });
+
+  test("a bullet that is only a promise is dropped from the plan", () => {
+    const note = renderPlanNote("1. Pull the July ledger rows and reconcile against the forecast.\n2. I'll come back as soon as I've got something.");
+    const bullets = note.split("\n").filter((l) => l.startsWith("- "));
+    assert.equal(bullets.length, 1);
+    assert.doesNotMatch(note, FORWARD_PROMISE);
+  });
+
+  test("a rendered plan NEVER carries a forward promise", () => {
+    for (const text of [
+      STEPS,
+      "1. Draft the memo. 2. I'll follow up with the numbers.",
+      "I'll pull the rows, then I'll come back as soon as I've got something.",
+    ]) {
+      const note = renderPlanNote(text);
+      if (note != null) assert.doesNotMatch(note, FORWARD_PROMISE, `"${note}" promises a return the sweep did not agree to`);
+    }
+  });
+
+  test("garbage in never throws", () => {
+    for (const bad of [null, undefined, 12, {}, []]) assert.equal(containsForwardPromise(bad), false);
+  });
+});