@patimweb/pi-teams 1.4.1 → 1.5.1

package/README.md

@@ -87,7 +87,10 @@ What it does, and what it deliberately does not:
   message is still unread for you in Teams. So switching listen mode back on
   answers what you missed while pi was not running — and a chat you already read
   in Teams stays quiet. A backlog is drained a few chats per tick and capped by
-  `maxTriggersPerHour`, so a long absence does not produce a burst.
+  `maxTriggersPerHour`, so a long absence does not produce a burst. A chat held
+  back by its `cooldownSeconds`, or by that hourly cap, is *delayed, never
+  dropped*: it keeps its place in line and is answered as soon as the wait is
+  over. `teams_watch action: status` shows how many are waiting right now.
 - **Never wakes for its own messages.** pi posts as you, so its own reply comes
   back as "my own message" and stops the loop.
 - **Respects the read rules.** A chat excluded by `permissions.read.chats` is
@@ -358,8 +361,8 @@ your own company can be `confirm` while a customer tenant stays `readonly`.
 
 ### AI disclosure footer
 
-Off by default. Switched on, every message, reply and edit pi sends in your name
-ends with a short note saying it was written by an AI:
+On by default. Every message, reply and edit pi sends in your name ends with a
+short note saying it was written by an AI:
 
 ```json
 "aiFooter": { "enabled": true, "text": "🤖 Erstellt mit pi (KI-Assistent)" }
@@ -367,11 +370,13 @@ ends with a short note saying it was written by an AI:
 
 | Key | Default | Meaning |
 |-----|---------|---------|
-| `enabled` | `false` | append the note to everything pi sends |
+| `enabled` | `true` | append the note to everything pi sends |
 | `text` | `🤖 Generated with pi (an AI agent)` | the wording; empty means the default |
 
-Set it globally or per account (the account level wins field by field, so one
-account can use its own wording while another keeps the global one).
+Turn it off with `"enabled": false` if the disclosure does not fit the people
+you write to. Set it globally or per account (the account level wins field by
+field, so one account can use its own wording while another keeps the global
+one).
 
 Details worth knowing:
 
@@ -427,7 +432,7 @@ teams_permissions:
 | `maxMessages` | `25` | default page size for message listings |
 | `audit` | `true` | append every write to `~/.pi/agent/pi-teams-audit.jsonl` |
 | `scopes` | see above | override the requested Graph scopes per account/tenant |
-| `aiFooter` | off | append an AI disclosure to every message pi sends — see above |
+| `aiFooter` | on | append an AI disclosure to every message pi sends — see above |
 | `graphBaseUrl` / `authorityHost` | Microsoft public cloud | sovereign cloud endpoints |
 
 ---
@@ -650,7 +655,8 @@ network connection.
 | "Blocked by configuration" | Your own scope rules. `teams_permissions action: test` shows which rule |
 | "cannot run on an app-only token" | Set `authMode: "interactive"` and run `teams_login` |
 | 403 reading channel messages | `ChannelMessage.Read.All` needs **admin** consent — see "Who has to approve what" |
-| Listen mode does nothing | `teams_watch action: status` says whether it is enabled and running. Only messages arriving *after* it was switched on wake pi |
+| Listen mode does nothing | `teams_watch action: status` says whether it is enabled and running, how many chats it tracks, and where the cursor lives. A chat you have already read in Teams stays quiet by design, and one held back by its cooldown or the hourly cap shows up as *waiting* |
+| Listen mode never answers one specific chat | `waiting` in `teams_watch action: status` says whether it is sitting out a `cooldownSeconds` window; chats it has already decided about are in the cursor under `~/.pi/agent/pi-teams-watch/` |
 | Listen mode answers too much | Narrow `watch.chats` and `watch.from`, raise `cooldownSeconds`, lower `maxTriggersPerHour` |
 | Listen mode stopped by itself | `teams_watch action: status` shows the last polling error; a revoked session or a sleeping laptop is the usual cause, and it resumes on its own |
 | Throttled | Graph rate limit; the client retries with back-off, then reports it |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.4.1",
+  "version": "1.5.1",
   "description": "Microsoft Teams integration for pi coding agent — acts fully as the signed-in user across multiple accounts and tenants: chats, channels, meetings, presence, with configurable guardrails",
   "keywords": [
     "pi-package",

package/skills/teams-collaboration/SKILL.md

@@ -114,11 +114,11 @@ instead of trying anyway.
 ## How to write as the user
 
 - Write in **their** voice. No "As an AI…", no signature, no note that a model
-  composed it, unless they ask for one. The one exception is configuration, not
-  judgement: with `aiFooter` switched on, the sending tools append the
-  disclosure themselves — do not write it into the body, or it arrives twice
-  (the tools detect it, but the user sees the text in the confirmation twice as
-  well, which looks like a mistake).
+  composed it — that disclosure is configuration, not judgement: the sending
+  tools append it themselves (`aiFooter`, on by default), so do not write it
+  into the body or it arrives twice (the tools detect the duplicate, but the
+  user sees the text in the confirmation twice as well, which looks like a
+  mistake).
 - Match the register of the conversation you just read. A channel post and a
   quick reply to a colleague are not the same thing.
 - Show the exact text and the destination before sending whenever the request

package/src/config/index.ts

@@ -137,13 +137,14 @@ export interface ResolvedWatchConfig {
 /**
  * The note pi can append to everything it sends in the user's name.
  *
- * Off by default, and deliberately so: pi writes as the user, and a disclosure
- * a recipient did not expect is a statement the user did not make. Where an
- * organisation wants it — a works council, a customer, a regulated process —
- * switching it on is a one-line change.
+ * On by default, and deliberately so: pi writes as the user, and a recipient
+ * who reads a message as coming from a colleague should be able to tell that a
+ * model composed it. A disclosure that depends on remembering to switch it on
+ * is not a disclosure, so the safe state is the default one — an organisation
+ * that does not want it turns it off with `enabled: false`.
  */
 export interface AiFooterConfig {
-	/** Append the note to every outgoing message (default: false) */
+	/** Append the note to every outgoing message (default: true) */
 	enabled?: boolean;
 	/** The note itself (default: see AI_FOOTER_DEFAULT) */
 	text?: string;
@@ -294,7 +295,7 @@ const DEFAULTS = {
 	authMode: "auto" as AuthMode,
 	maxMessages: 25,
 	audit: true,
-	aiFooter: false,
+	aiFooter: true,
 	graphBaseUrl: "https://graph.microsoft.com/v1.0",
 	authorityHost: "https://login.microsoftonline.com",
 };
@@ -901,7 +902,7 @@ const TEMPLATE_JSON = `{
   "safetyLevel": "confirm",
   "maxMessages": 25,
   "audit": true,
-  "aiFooter": { "enabled": false, "text": "🤖 Generated with pi (an AI agent)" }
+  "aiFooter": { "enabled": true, "text": "🤖 Generated with pi (an AI agent)" }
 }
 `;
 

package/src/status.ts

@@ -81,7 +81,12 @@ export function buildConnectionLabel(card: ConnectionCard | undefined): string {
 	if (!card.signedIn) return `Teams · ${card.account} · not signed in`;
 
 	const scope = card.tenant === card.account ? card.account : `${card.account}/${card.tenant}`;
-	const listening = card.watching ? " · 👂 listening" : "";
+	// A monochrome mark, not an emoji: the rest of the label is drawn in the
+	// terminal's own font (the ✓ included), and a colour glyph next to it looks
+	// like a different interface. ◉ reads as "live", which is what the label is
+	// saying — and it survives a terminal without emoji fonts, where 👂 would
+	// come out as tofu.
+	const listening = card.watching ? " · ◉ listening" : "";
 	return `✓ Teams · ${scope}${card.user ? ` · ${card.user}` : ""}${listening}`;
 }
 

package/src/tools/teams-send-chat-message.ts

@@ -5,10 +5,19 @@
  * from the user typing it. Hence the order of operations — resolve the chat,
  * check the chat rules, check every participant against the people rules,
  * resolve the mentions, send, then record the audit entry.
+ *
+ * The last step is the read cursor. Sending from Graph does not move it — only
+ * the user opening the chat, or teams_mark_read, does — so without this a chat
+ * pi has just answered keeps its unread marker in Teams, which is the one thing
+ * that looks like nobody dealt with it. Replying is reading, so the message
+ * would arrive with the chat still bold; the mark is best effort and comes last,
+ * because a send that went out must not be reported as failed.
  */
 
 import { Type } from "typebox";
+import { setChatReadState } from "../graph/chats.ts";
 import { sendChatMessage } from "../graph/messages.ts";
+import { formatGraphError } from "../utils/errors.ts";
 import { resolveUserId } from "../graph/me.ts";
 import { auditWrite } from "../safety/audit.ts";
 import { assertAccess } from "../safety/index.ts";
@@ -69,7 +78,7 @@ export const teamsSendChatMessageTool = {
 	promptGuidelines: [
 		"Write the message in the user's voice — it is sent from their account, not from an assistant.",
 		"Show the user the exact text before sending when the intent is even slightly ambiguous.",
-		"Do not add signatures, disclaimers, or a note that the message was written by an AI unless the user asks.",
+		"Do not add signatures, or a note that the message was written by an AI: the sending tool appends the configured AI disclosure itself (on by default), so writing one into the body duplicates it.",
 		"Format for a chat, not for a document: lead with the answer, three short paragraphs at most, bullets for lists. Bold, italics, code, links and bullets are rendered; headings become bold lines and tables are not supported — keep those out.",
 		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
@@ -135,6 +144,18 @@ export const teamsSendChatMessageTool = {
 					summary: truncate(body, 200),
 				});
 
+				// Replying is reading: clear the unread marker the answer was written for.
+				// Deliberately after the audit entry, so the message that went out is
+				// recorded even when the read-mark cannot be moved.
+				let readNote = "";
+				if (me) {
+					try {
+						await setChatReadState(conn, chat.id, me, true, { signal });
+					} catch (err) {
+						readNote = `\n\n⚠️ The chat could not be marked as read: ${formatGraphError(err)}`;
+					}
+				}
+
 				return textResult(
 					[
 						`✅ Message sent to **${chat.label}** as ${me?.displayName ?? "you"} (${connectionLabel(conn)}).`,
@@ -142,7 +163,7 @@ export const teamsSendChatMessageTool = {
 						`> ${truncate(body, 300)}`,
 						"",
 						`messageId: ${sent.id}`,
-					].join("\n"),
+					].join("\n") + readNote,
 					{ chatId: chat.id, messageId: sent.id },
 				);
 			} catch (err) {

package/src/tools/teams-watch.ts

@@ -46,7 +46,8 @@ const CURSOR_NOTES = [
 		+ "on therefore answers what you missed, and a chat you have already read in Teams stays quiet.",
 	"",
 	"A backlog is drained over several ticks and capped by the hourly wake limit, so a long absence does "
-		+ "not produce a burst of answers.",
+		+ "not produce a burst of answers. A chat held back by its cooldown or by that limit is delayed, "
+		+ "never dropped: it stays open and is answered as soon as the wait is over.",
 ].join("\n");
 
 /** Renders the effective settings the same way the config file would. */
@@ -93,6 +94,12 @@ function runtimeLines(runtime: WatchRuntimeStatus | undefined, conn: TeamsConnec
 		`- chats tracked: ${runtime.trackedChats}`,
 		`- woken this hour: ${runtime.wakesThisHour}`,
 	];
+	if (runtime.waiting > 0) {
+		lines.push(
+			`- waiting: ${runtime.waiting} chat(s) — held back by their cooldown or by the wake limit, "
+				+ "and answered once that clears`,
+		);
+	}
 	if (runtime.lastTickAt) {
 		lines.push(`- last poll: ${new Date(runtime.lastTickAt).toLocaleTimeString()}`);
 	}
@@ -115,9 +122,8 @@ export const teamsWatchTool = {
 	name: "teams_watch",
 	description:
 		"Control listen mode: pi polls your Teams chats and turns an incoming message into a prompt it answers. " +
-		"A chat wakes it when it has moved since pi last looked, so switching listen mode on also answers " +
-		"what arrived while pi was not running; only the very first run on an account records history " +
-		"without answering it. " +
+		"A chat wakes it when it has moved since pi last looked, so switching listen mode on also answers "
+			+ "what arrived while pi was not running. " +
 		"Use action 'status' to see the current settings, 'enable' or 'disable' to switch it, and the optional " +
 		"fields to narrow what may wake pi (chat patterns, mentions only, interval, cooldown, hourly limit). " +
 		"The watcher runs in the extension session; this tool changes the configuration it reads.",
@@ -216,7 +222,7 @@ export const teamsWatchTool = {
 							"",
 							...runtimeLines(runtime, conn),
 							"",
-							...CURSOR_NOTES,
+							CURSOR_NOTES,
 						].join("\n"),
 						{ watch, runtime },
 					);

package/src/watch/cursor.ts

@@ -15,6 +15,11 @@
  * the stored one. Written after every tick, so a crash costs nothing but the
  * tick it died in.
  *
+ * What lands here is a *decision*, not a sighting: a chat whose wake was only
+ * postponed — inside its cooldown, or over the hourly limit — is deliberately
+ * kept out of the file (see `noteDeferral` in ./index.ts), because an entry here
+ * means the watcher will never look at that chat again.
+ *
  * One file per account **and** tenant, next to the token cache: two accounts in
  * one process must not share a cursor, and neither must a guest tenant beneath
  * the same account.

package/src/watch/index.ts

@@ -51,6 +51,20 @@ export interface WatchState {
 	lastTriggered: Map<string, number>;
 	/** epoch ms of every wake, pruned to the last hour */
 	triggers: number[];
+	/**
+	 * chatId → epoch ms before which this chat must not be looked at again.
+	 *
+	 * The counterpart of `seen`, and the whole point of the pair: a chat whose
+	 * decision was only *postponed* — inside its cooldown, or held back by the
+	 * hourly wake limit — is deliberately **not** written to the cursor, because
+	 * the cursor means "pi has looked at this and will not look again". A message
+	 * written down there is a message nobody ever answers.
+	 *
+	 * In memory on purpose: it only saves the Graph calls of re-examining the chat
+	 * every tick until the wait is over, so losing it on a restart costs one extra
+	 * examination — never a message.
+	 */
+	retryAfter: Map<string, number>;
 }
 
 /**
@@ -67,7 +81,42 @@ export const MAX_CHAT_ATTEMPTS = 3;
  *   Omitted means the very first run, which is the only run that skips history.
  */
 export function createWatchState(seen?: Iterable<[string, string]>): WatchState {
-	return { seen: new Map(seen), attempts: new Map(), lastTriggered: new Map(), triggers: [] };
+	return {
+		seen: new Map(seen),
+		attempts: new Map(),
+		lastTriggered: new Map(),
+		triggers: [],
+		retryAfter: new Map(),
+	};
+}
+
+/**
+ * Record that a chat has been looked at and decided.
+ *
+ * "Decided" is the operative word: only a final decision may write the cursor,
+ * since the cursor is what stops the watcher from ever looking at that chat
+ * again. A postponed chat goes to `noteDeferral` instead.
+ */
+export function settleChat(state: WatchState, chatId: string, marker: string): void {
+	state.seen.set(chatId, marker);
+	state.retryAfter.delete(chatId);
+}
+
+/**
+ * Keep a chat open — and out of the batch — until `until`.
+ *
+ * Not writing the cursor is what keeps the message; this is only the throttle
+ * on how often the chat is re-read while it waits.
+ */
+export function noteDeferral(state: WatchState, chatId: string, until: number): void {
+	state.retryAfter.set(chatId, until);
+}
+
+/** How many chats are waiting out a cooldown or the wake limit right now. */
+export function waitingCount(state: WatchState, now: number): number {
+	let waiting = 0;
+	for (const until of state.retryAfter.values()) if (until > now) waiting += 1;
+	return waiting;
 }
 
 /** Record a failed examination; true while the chat is still worth retrying. */
@@ -122,6 +171,12 @@ export function pruneState(state: WatchState, now: number): void {
 		state.seen = new Map(byMarker.slice(0, MAX_CURSOR_ENTRIES));
 	}
 
+	// Waiting chats expire by themselves — a deferral can never outlive the hour
+	// the wake limit looks at, so there is nothing to bound here.
+	for (const [chatId, until] of state.retryAfter) {
+		if (until <= now) state.retryAfter.delete(chatId);
+	}
+
 	// Counters are bounded by size rather than by the cursor: a chat that keeps
 	// failing is deliberately *not* in the cursor, and its counter is what stops
 	// it from being retried forever.
@@ -149,6 +204,7 @@ export function chatsToExamine(
 	state: WatchState,
 	chats: ChatSummary[],
 	watch: ResolvedWatchConfig,
+	now: number,
 ): ChatSummary[] {
 	return chats.filter((chat) => {
 		if (!isWatchedChat(chat, watch)) return false;
@@ -158,7 +214,15 @@ export function chatsToExamine(
 		// "new" — and never marked, which costs no Graph call at all.
 		if (!marker) return false;
 
-		return state.seen.get(chat.id) !== marker;
+		if (state.seen.get(chat.id) === marker) return false;
+
+		// Moved, but the decision on it is only postponed: the chat is still open
+		// (it is not in the cursor), but looking at it again right now would only
+		// re-read the same message. Deliberately after the cursor check, and
+		// deliberately out of the batch rather than in it — a chat waiting out its
+		// cooldown must not cost another chat its slot in the tick.
+		const until = state.retryAfter.get(chat.id);
+		return until === undefined || until <= now;
 	});
 }
 
@@ -192,15 +256,91 @@ export function isWatchedSender(message: MessageSummary, watch: ResolvedWatchCon
 	return watch.from.some((pattern) => candidates.some((candidate) => matchesPattern(pattern, candidate)));
 }
 
+// ---------------------------------------------------------------------------
+// What the answer has to cover
+// ---------------------------------------------------------------------------
+
+/**
+ * How many recent messages of a chat the watcher pulls in.
+ *
+ * One would be enough to decide *whether* to wake, and that is what this used to
+ * be — but not enough to answer well: someone who sends three lines in a row
+ * leaves three open messages, and a reply to only the newest reads as if the
+ * other two were ignored. The window is small on purpose; it only exists to
+ * carry the context of the newest message, not to replay the conversation.
+ */
+export const WATCH_MESSAGE_WINDOW = 10;
+
+/**
+ * The messages in this chat that are still open for the user, oldest first.
+ *
+ * "Open" is the Teams read cursor talking, exactly as `isUnread` means it: a
+ * message from somebody else that the user has not caught up with yet. Messages
+ * of my own are dropped — pi posts as the user, so they are the answers that
+ * were already given, not questions waiting for one.
+ *
+ * `messages` is newest first, as Graph returns it. A `readAt` Teams will not
+ * give is treated as "all of them are open" rather than as settled, for the same
+ * reason `isUnread` does: a read state we cannot read must not silently switch
+ * listen mode off.
+ */
+export function openMessages(
+	messages: MessageSummary[],
+	readAt: string | undefined,
+	me: SignedInUser | undefined,
+): MessageSummary[] {
+	const read = readAt ? new Date(readAt).getTime() : Number.NaN;
+	const known = Number.isFinite(read);
+
+	return messages
+		.filter((entry) => {
+			if (entry.deletedDateTime) return false;
+			if (isFromMe(entry.from, me)) return false;
+			if (!known) return true;
+
+			const at = entry.createdDateTime ? new Date(entry.createdDateTime).getTime() : Number.NaN;
+			return Number.isFinite(at) && at > read;
+		})
+		.reverse();
+}
+
 // ---------------------------------------------------------------------------
 // Whether a message should wake pi
 // ---------------------------------------------------------------------------
 
-export type WakeDecision = { wake: true } | { wake: false; reason: string };
+export type WakeDecision =
+	| { wake: true }
+	| {
+			wake: false;
+			reason: string;
+			/**
+			 * Set when the skip is only for now: ms to wait before looking again.
+			 * Absent means the decision is final — this message is not for pi.
+			 */
+			retryAfterMs?: number;
+		};
 
 const WAKE: WakeDecision = { wake: true };
+
+/** Final: this message will never be one of pi's. */
 const skip = (reason: string): WakeDecision => ({ wake: false, reason });
 
+/** Only for now: the message stays open and is looked at again after the wait. */
+const defer = (reason: string, retryAfterMs: number): WakeDecision => ({
+	wake: false,
+	reason,
+	retryAfterMs: Math.max(MIN_RETRY_MS, Math.round(retryAfterMs)),
+});
+
+/**
+ * Floor on a retry delay.
+ *
+ * A cooldown that is a second away, or a wake limit about to slide, would
+ * otherwise turn the deferral into "examine this chat again on every tick" —
+ * the point of waiting is to not pay for the same Graph calls until it matters.
+ */
+const MIN_RETRY_MS = 5_000;
+
 /**
  * Is the newest message in this chat still unread for the user?
  *
@@ -227,8 +367,13 @@ export function isUnread(chat: ChatSummary, lastMessageReadAt?: string): boolean
  * Should this message wake pi?
  *
  * Ordered so the cheapest and most obvious reason to stay quiet is also the
- * one that gets reported — a wrong wake costs a model turn, a wrong silence
- * costs nothing but the reason in the log.
+ * one that gets reported.
+ *
+ * The two kinds of "no" are told apart here, and it matters: a message from
+ * somebody pi does not listen to will never become an answer, while a chat in
+ * its cooldown or a burst over the hourly limit is only waiting. Those two are
+ * returned with a `retryAfterMs`, and the loop uses it to keep the chat open
+ * instead of writing it off in the cursor.
  */
 export function shouldWake(
 	chat: ChatSummary,
@@ -245,17 +390,34 @@ export function shouldWake(
 	if (!isWatchedSender(message, watch)) return skip("the sender is outside the configured listen list");
 	if (watch.mentionOnly && !mentionsMe(message, me)) return skip("the chat is set to mentions only");
 	if (watch.maxTriggersPerHour > 0 && wakesThisHour(state, now) >= watch.maxTriggersPerHour) {
-		return skip("the hourly wake limit is reached");
+		return defer(
+			"the hourly wake limit is reached",
+			nextWakeSlot(state, now, watch.maxTriggersPerHour) - now,
+		);
 	}
 
 	const last = state.lastTriggered.get(chat.id);
 	if (last !== undefined && now - last < watch.cooldownSeconds * 1000) {
-		return skip("this chat is inside its cooldown");
+		return defer("this chat is inside its cooldown", last + watch.cooldownSeconds * 1000 - now);
 	}
 
 	return WAKE;
 }
 
+/**
+ * When the next wake fits under the hourly limit.
+ *
+ * The limit is a sliding window, not a bucket that empties on the hour, so the
+ * answer is "when the oldest wake of the last hour falls out of it". That is
+ * what keeps a burst — a Monday morning, a release — from silencing a chat for
+ * the rest of the hour.
+ */
+export function nextWakeSlot(state: WatchState, now: number, maxPerHour: number): number {
+	const recent = state.triggers.filter((at) => now - at < 3600_000).sort((a, b) => a - b);
+	if (maxPerHour < 1 || recent.length < maxPerHour) return now;
+	return recent[recent.length - maxPerHour] + 3600_000;
+}
+
 /**
  * Record that pi was woken for a chat.
  *

package/src/watch/loop.ts

@@ -30,12 +30,17 @@ import {
 	chatsToExamine,
 	createWatchState,
 	isUnread,
+	noteDeferral,
 	noteFailure,
 	noteSuccess,
 	noteWake,
+	openMessages,
 	pruneState,
+	settleChat,
 	shouldWake,
+	waitingCount,
 	wakesThisHour,
+	WATCH_MESSAGE_WINDOW,
 	type WatchState,
 } from "./index.ts";
 
@@ -46,7 +51,17 @@ import {
 /** One message that deserves a model turn. */
 export interface WatchEvent {
 	chat: ChatSummary;
+	/** The newest message in the chat — the one the wake was decided on */
 	message: MessageSummary;
+	/**
+	 * Everything still open in that chat, oldest first, the newest included.
+	 *
+	 * Waking up is about one message, answering is usually about more than one:
+	 * three lines sent in a row are three open messages, and answering only the
+	 * last of them is what the user notices. Empty means the trigger was the only
+	 * thing the read cursor left open.
+	 */
+	backlog?: MessageSummary[];
 	/** Epoch ms the wake was decided */
 	wokeAt: number;
 	/** Who pi is acting as, carried along for the prompt */
@@ -66,6 +81,12 @@ export interface WatchRuntimeStatus {
 	wakesThisHour: number;
 	/** Chats seen so far — a quick sanity signal that the loop is alive */
 	trackedChats: number;
+	/**
+	 * Chats still open but held back right now — inside their cooldown, or waiting
+	 * for a slot under the hourly limit. The visible form of "not lost, not yet
+	 * answered": without it, a burst that hits the limit looks like silence.
+	 */
+	waiting: number;
 	/** How many chats had moved when the watcher came up, before the per-tick cap */
 	catchUp?: number;
 	/** Of those, how many the user had already read in Teams */
@@ -88,7 +109,11 @@ export const MAX_EXAMINATIONS_PER_TICK = 5;
 export interface WatchTickDeps {
 	/** Newest chats, most recent activity first */
 	listChats: () => Promise<ChatSummary[]>;
-	/** The most recent messages of one chat, newest first */
+	/**
+	 * A window of the chat's most recent messages, newest first — enough to find
+	 * the newest one and whatever the user has not read yet (see
+	 * `WATCH_MESSAGE_WINDOW`).
+	 */
 	listMessages: (chatId: string) => Promise<MessageSummary[]>;
 	/**
 	 * The user's read cursor for one chat (`viewpoint.lastMessageReadDateTime`).
@@ -116,6 +141,8 @@ export interface WatchTickResult {
 	pending: number;
 	/** Of the examined ones, how many the user had already read */
 	alreadyRead: number;
+	/** Of the examined ones, how many were only postponed */
+	deferred: number;
 	wakes: WatchEvent[];
 }
 
@@ -127,6 +154,12 @@ export interface WatchTickResult {
  * without one every chat is compared against the user's own read state on the
  * very first tick. What keeps that from becoming a flood is the per-tick cap
  * and the hourly wake limit, not a window that quietly drops messages.
+ *
+ * The one rule the whole function hangs on: **the cursor is written only for a
+ * decision that is final.** It is the record of what pi has looked at, so what
+ * lands in it is never looked at again — which is right for a message from
+ * somebody pi does not listen to, and wrong for a message that was merely too
+ * early. Those go to `noteDeferral` instead and keep their place in line.
  */
 export async function runWatchTick(
 	deps: WatchTickDeps,
@@ -139,17 +172,22 @@ export async function runWatchTick(
 
 	const chats = (await deps.listChats()).filter((chat) => deps.allowed?.(chat) ?? true);
 
-	const candidates = chatsToExamine(state, chats, watch);
+	const candidates = chatsToExamine(state, chats, watch, now);
 	const batch = candidates.slice(0, MAX_EXAMINATIONS_PER_TICK);
 
 	const wakes: WatchEvent[] = [];
 	let alreadyRead = 0;
+	let deferred = 0;
 
 	for (const chat of batch) {
-		// Mark first, then undo the mark if this chat cannot be examined: a chat
-		// that fails must not be retried forever, but a token renewal must not turn
-		// into a message nobody ever answers.
-		state.seen.set(chat.id, activityMarker(chat));
+		const marker = activityMarker(chat);
+
+		// A chat that cannot be read must not occupy a batch slot on every tick, and
+		// a token renewal must not turn into a message nobody ever answers: it is
+		// written off only once it has used up its attempts.
+		const failed = () => {
+			if (!noteFailure(state, chat.id)) settleChat(state, chat.id, marker);
+		};
 
 		// The read cursor first: a chat the user has already opened in Teams ends
 		// here, one Graph call in, before the message is even fetched.
@@ -157,12 +195,13 @@ export async function runWatchTick(
 		try {
 			readAt = await deps.readState(chat.id);
 		} catch {
-			if (noteFailure(state, chat.id)) state.seen.delete(chat.id);
+			failed();
 			continue;
 		}
 
 		if (!isUnread(chat, readAt)) {
 			noteSuccess(state, chat.id);
+			settleChat(state, chat.id, marker);
 			alreadyRead += 1;
 			continue;
 		}
@@ -173,27 +212,52 @@ export async function runWatchTick(
 		} catch {
 			// A single unreadable chat must not end the tick — the rest of the
 			// list is still worth examining.
-			if (noteFailure(state, chat.id)) state.seen.delete(chat.id);
+			failed();
 			continue;
 		}
 
 		noteSuccess(state, chat.id);
 
 		const message = messages.find((entry) => !entry.deletedDateTime) ?? messages[0];
-		if (!message) continue;
+		if (!message) {
+			settleChat(state, chat.id, marker);
+			continue;
+		}
 
 		const decision = shouldWake(chat, message, me, watch, state, now);
-		if (!decision.wake) continue;
+		if (!decision.wake) {
+			if (decision.retryAfterMs !== undefined) {
+				// Postponed, not answered and not written off: the chat keeps its
+				// message and waits out the cooldown or the wake limit.
+				noteDeferral(state, chat.id, now + decision.retryAfterMs);
+				deferred += 1;
+			} else {
+				settleChat(state, chat.id, marker);
+			}
+			continue;
+		}
 
 		noteWake(state, chat.id, now);
-		wakes.push({ chat, message, wokeAt: now, me });
+		settleChat(state, chat.id, marker);
+
+		// The answer has to cover the whole open thread, not just its newest line:
+		// the trigger message is the reason for the wake, the backlog is the reason
+		// for a reply that sounds like the conversation was read.
+		const backlog = openMessages(messages, readAt, me);
+		wakes.push({
+			chat,
+			message,
+			backlog: backlog.length > 0 ? backlog : [message],
+			wokeAt: now,
+			me,
+		});
 	}
 
 	// Written even when nothing woke: marking a chat examined is the progress
-	// that must survive a restart.
+	// that must survive a restart. Postponed chats are absent from it on purpose.
 	if (batch.length > 0) deps.persistCursor?.(state.seen);
 
-	return { examined: batch.length, pending: candidates.length, alreadyRead, wakes };
+	return { examined: batch.length, pending: candidates.length, alreadyRead, deferred, wakes };
 }
 
 // ---------------------------------------------------------------------------
@@ -274,6 +338,7 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 		intervalSeconds: watch.intervalSeconds,
 		wakesThisHour: 0,
 		trackedChats: 0,
+		waiting: 0,
 	};
 
 	const schedule = (delayMs: number) => {
@@ -295,7 +360,8 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 			const result = await runWatchTick(
 				{
 					listChats: () => listChats(connection, { max: 50, meId: me?.id }),
-					listMessages: (chatId) => listChatMessages(connection, chatId, { max: 1 }),
+					listMessages: (chatId) =>
+						listChatMessages(connection, chatId, { max: WATCH_MESSAGE_WINDOW }),
 					readState: async (chatId) => (await getChatViewpoint(connection, chatId))?.lastMessageReadAt,
 					now: () => Date.now(),
 					allowed: (chat) => hasAccess(connection, "read", "chats", chatCandidates(chat)),
@@ -318,6 +384,7 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 			status.lastError = undefined;
 			status.wakesThisHour = wakesThisHour(state, status.lastTickAt);
 			status.trackedChats = state.seen.size;
+			status.waiting = waitingCount(state, status.lastTickAt);
 
 			for (const event of result.wakes) {
 				status.lastWakeAt = event.wokeAt;

package/src/watch/prompt.ts

@@ -6,9 +6,13 @@
  * what pi does with a message it was woken for is decided here, and nothing in
  * the polling loop should be able to change it.
  *
- * Two things the prompt must always carry: the chat ID — so the reply cannot
+ * Three things the prompt must always carry: the chat ID — so the reply cannot
  * land in the wrong conversation, since pi posts as a person and a name is not
- * an identifier — and the instruction that doing nothing is a valid answer.
+ * an identifier — the instruction that doing nothing is a valid answer, and
+ * every message still open in that chat. The last one is not decoration: a wake
+ * is decided on the newest message, but people send three lines in a row, and a
+ * reply that answers only the last of them is the failure mode this prompt
+ * exists to prevent.
  */
 
 import type { MessageSummary, SignedInUser } from "../types.ts";
@@ -18,6 +22,45 @@ function senderName(message: MessageSummary): string {
 	return message.from?.displayName ?? message.from?.upn ?? "someone";
 }
 
+/** `17:00`, or nothing when Graph did not date the message. */
+function timeOf(message: MessageSummary): string {
+	if (!message.createdDateTime) return "";
+	const at = new Date(message.createdDateTime);
+	return Number.isFinite(at.getTime()) ? at.toLocaleTimeString() : "";
+}
+
+function quote(text: string | undefined): string {
+	const body = text?.trim() ? text.trim() : "(no text content — open the chat to see it)";
+	return body
+		.split("\n")
+		.map((line) => `> ${line}`)
+		.join("\n");
+}
+
+/**
+ * The open messages of the chat, oldest first.
+ *
+ * Falls back to the trigger message alone when the backlog is missing — a wake
+ * without one still has to produce a usable prompt.
+ */
+function openThread(event: WatchEvent): MessageSummary[] {
+	const backlog = event.backlog?.filter((entry) => !entry.deletedDateTime) ?? [];
+	return backlog.length > 0 ? backlog : [event.message];
+}
+
+/** One numbered block per open message, oldest first. */
+function renderThread(messages: MessageSummary[]): string {
+	return messages
+		.map((entry, index) => {
+			const newest = index === messages.length - 1;
+			const stamp = timeOf(entry);
+			const heading = [stamp, senderName(entry)].filter(Boolean).join(" · ");
+			const label = newest ? `${heading} — newest` : heading;
+			return [`> ${index + 1}. ${label}`, quote(entry.text)].join("\n");
+		})
+		.join("\n>\n");
+}
+
 /**
  * The prompt for one wake.
  *
@@ -26,28 +69,49 @@ function senderName(message: MessageSummary): string {
  */
 export function composeWatchPrompt(event: WatchEvent, me?: SignedInUser): string {
 	const { chat, message } = event;
-	const text = message.text?.trim() ? message.text.trim() : "(no text content — open the chat to see it)";
+	const thread = openThread(event);
 	const at = message.createdDateTime ? new Date(message.createdDateTime).toLocaleString() : "just now";
 
-	return [
-		"An incoming Microsoft Teams message arrived while you were idle.",
+	const header = [
+		"The following Microsoft Teams message arrived while you were idle.",
 		"",
 		`- Chat: ${chat.label} (${chat.chatType})`,
 		`- From: ${senderName(message)}`,
 		`- At: ${at}`,
 		`- Chat ID: ${chat.id}`,
+	];
+
+	const body =
+		thread.length > 1
+			? [
+					"",
+					`Unanswered messages in this chat (${thread.length}), oldest first:`,
+					"",
+					renderThread(thread),
+				]
+			: ["", "Message:", "", quote(message.text)];
+
+	const decision =
+		thread.length > 1
+			? [
+					"Decide whether these need an answer.",
+					"",
+					"All of them are still unread in Teams, and they arrived together as one conversation. Answer every " +
+						"one of them, not just the newest — one short reply can cover all of it, but a reply that " +
+						"ignores the earlier messages is wrong even when its wording is fine.",
+				]
+			: ["Decide whether this needs an answer."];
+
+	return [
+		...header,
+		...body,
 		"",
-		"Message:",
-		text
-			.split("\n")
-			.map((line) => `> ${line}`)
-			.join("\n"),
-		"",
-		"Decide whether this needs an answer.",
+		...decision,
 		"",
 		`- If it does: reply with teams_send_chat_message, passing chat: "${chat.id}". pi posts as ` +
 			`${me?.displayName ?? "me"}, so write in my voice, in the language of the conversation, as briefly as ` +
-			"the message allows. No greeting boilerplate, no signature.",
+			"the message allows. No greeting boilerplate, no signature, and no note that a model wrote it — " +
+			"the sending tool appends the configured AI disclosure itself.",
 		"- If it does not: say so in one line and stop.",
 		"",
 		"Format it for a chat bubble, not a document: the answer first, three short paragraphs at most, " +