@patimweb/pi-teams 1.5.0 → 1.6.0

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
@@ -652,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.5.0",
+  "version": "1.6.0",
   "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

@@ -131,36 +131,91 @@ instead of trying anyway.
 ## How to format a Teams message
 
 A Teams chat is a chat bubble, not a document. What arrives badly is long
-prose: the reader has to hunt for the point, and it reads as if a machine wrote
-it. The body is rendered as HTML — markdown is converted for you, so write
+prose: the answer is buried, the reader has to hunt for it, and it reads as if a
+machine wrote it. "Keep it short" does not fix that on its own — a shape does.
+The body is rendered as HTML, and markdown is converted for you, so write
 markdown and let the tool do the rest.
 
-**Reach for this shape, not for paragraphs:**
+**The shape, which is nearly always this:**
 
 ```
-Kurz: die QA-Umgebung läuft wieder.
+QA läuft wieder.
 
 - Ursache: abgelaufenes Zertifikat
 - Fix: erneuert und neu deployt
 - Offen: Monitoring für 90 Tage
 ```
 
-- **Lead with the answer.** The first line should work as the whole message for
-  someone who reads nothing else.
-- **Three short paragraphs at most.** If it needs more, it is a document — put
-  it in a file or a wiki page and link it.
+Line one is the answer. Then a blank line, then only what the reader needs in
+order to act on it. Five lines is already a long chat message.
+
+**Before and after.** Both versions say the same thing; only one is a chat:
+
+> **So nicht:** Ich habe mir die QA-Umgebung jetzt angeschaut und konnte den
+> Fehler reproduzieren. Das Problem liegt darin, dass das TLS-Zertifikat
+> abgelaufen war, wodurch alle Requests fehlgeschlagen sind. Ich habe es dann
+> erneuert und die Umgebung neu deployt, jetzt läuft wieder alles. Ich würde
+> allerdings noch empfehlen, das Monitoring einzurichten, damit das nicht
+> wieder passiert.
+
+> **So:** QA läuft wieder.
+>
+> - Ursache: abgelaufenes TLS-Zertifikat
+> - Fix: erneuert und neu deployt
+> - Empfehlung: Monitoring auf die Ablaufdaten
+
+**Three skeletons that cover most messages:**
+
+*Antwort auf eine Frage* — the answer, then at most one line of reasoning:
+
+```
+Ja, Freitag passt.
+
+Ich bin bis 14:00 im Workshop, danach jederzeit.
+```
+
+*Status* — outcome first, then what is still open:
+
+```
+Deployment ist durch, Release Notes stehen im Wiki: <Link>
+
+Offen: Smoke-Test auf Produktion, mache ich heute Nachmittag.
+```
+
+*Entscheidung nötig* — the decision, the options, the deadline:
+
+```
+Ich brauche bis morgen eine Entscheidung zum Sync-Intervall.
+
+- 5 Min: schnell, ~3× Last auf dem SAP-System
+- 15 Min: entspannt, dafür Verzögerung im Reporting
+```
+
+**Rules**
+
+- **The first line carries the message.** Someone who reads only that line
+  should know the outcome.
 - **Bullets for anything enumerable** — causes, options, next steps. Three items
-  and up belong in a list, not in a sentence with commas.
+  and up are a list; two are a sentence.
+- **One idea per line.** A line break is free; a clause chain held together by
+  commas is not.
 - **Bold the one thing that must not be missed**, and only that. Bold used
   everywhere is bold nowhere.
 - **Numbers, names and dates exactly as they are.** Do not round a figure or
   paraphrase a deadline into something friendlier.
 - **One question per message.** Two questions get one answer.
+- **No greeting and no closing.** "Hallo zusammen", "Ich habe mir das mal
+  angeschaut", "Kurz zusammengefasst:" and "Sag Bescheid, wenn du Fragen hast"
+  are all noise in a chat. The message starts with the answer and stops when it
+  is done.
+- **Over five lines, it is a document.** Put it in a wiki page or a file and send
+  the link with one sentence around it.
 
 **What Teams renders:** `**bold**`, `*italic*`, `` `code` ``, `~~struck~~`,
-`[label](url)`, `- bullets`, `1. numbered`, ``` fences. A `# heading` arrives as
-a bold line — fine for structure, not for hierarchy. **Tables are not supported
-in a chat**: convert them to bullets, or put the table in a file and link it.
+`[label](url)`, `- bullets`, `1. numbered`, and code fences. A `# heading`
+arrives as a bold line — fine for structure, not for hierarchy. **Tables are not
+supported in a chat**: convert them to bullets, or put the table in a file and
+link it.
 
 **Language and tone:** answer in the language of the conversation, in the
 register of the people in it. Short forms are normal in a chat ("passt", "ok,
@@ -323,9 +378,9 @@ teams_watch:
 2. If an answer is warranted, send it with `teams_send_chat_message` to the
    **chat ID from the prompt** — never re-resolve the chat by name. pi posts as
    the user, so the wrong chat is a wrong statement in the user's name.
-3. Keep it to the shape in *How to format a Teams message*: answer first, three
-   short paragraphs at most, bullets for lists. An unrequested message has to be
-   readable at a glance.
+3. Keep it to the shape in *How to format a Teams message*: the answer on the
+   first line, at most five short lines, bullets for anything enumerable. An
+   unrequested message has to be readable at a glance.
 4. If no answer is warranted, say so in one line and stop. Do not react, do not
    touch other chats, do not post to a channel.
 

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-channel-message.ts

@@ -10,6 +10,7 @@ import { Type } from "typebox";
 import { replyToChannelMessage, sendChannelMessage } from "../graph/messages.ts";
 import { resolveUserId } from "../graph/me.ts";
 import { auditWrite } from "../safety/audit.ts";
+import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
 import { assertAccess } from "../safety/index.ts";
 import { truncate } from "../utils/formatting.ts";
@@ -58,10 +59,7 @@ async function resolveMentions(
 const sharedParams = {
 	channel: Type.String({ description: "Channel name or ID, or a 'Team/Channel' path" }),
 	team: Type.Optional(Type.String({ description: "Team name or ID (omit when using a path)" })),
-	body: Type.String({
-			description:
-				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
-		}),
+	body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 	account: AccountParam,
 	tenant: TenantParam,
 	mentions: Type.Optional(
@@ -85,7 +83,7 @@ export const teamsSendChannelMessageTool = {
 	promptGuidelines: [
 		"Write in the user's voice — the post is attributed to them, not to an assistant.",
 		"Show the exact text and the target channel before posting when there is any ambiguity.",
-		"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.",
+		CHAT_SHAPE_GUIDELINE,
 		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 
@@ -180,6 +178,7 @@ export const teamsReplyChannelMessageTool = {
 		messageId: Type.String({ description: "ID of the thread's opening message" }),
 	}),
 	promptSnippet: "Reply in a Teams channel thread as the user",
+	promptGuidelines: [CHAT_SHAPE_GUIDELINE],
 
 	async execute(
 		_toolCallId: string,

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

@@ -5,13 +5,23 @@
  * 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";
+import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
 import { truncate } from "../utils/formatting.ts";
 import { requireChat } from "./resolve.ts";
@@ -47,10 +57,7 @@ export const teamsSendChatMessageTool = {
 		"where the mention should appear.",
 	parameters: Type.Object({
 		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
-		body: Type.String({
-			description:
-				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
-		}),
+		body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 		account: AccountParam,
 		tenant: TenantParam,
 		mentions: Type.Optional(
@@ -70,7 +77,7 @@ export const teamsSendChatMessageTool = {
 		"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, 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.",
+		CHAT_SHAPE_GUIDELINE,
 		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 
@@ -135,6 +142,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 +161,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-update-message.ts

@@ -14,6 +14,7 @@
 import { Type } from "typebox";
 import { updateMessage } from "../graph/messages.ts";
 import { auditWrite } from "../safety/audit.ts";
+import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
 import { requireChat } from "./resolve.ts";
 import {
@@ -36,7 +37,7 @@ export const teamsUpdateMessageTool = {
 		"Use this instead of deleting a message and sending a corrected copy.",
 	parameters: Type.Object({
 		messageId: Type.String({ description: "ID of the message to edit" }),
-		body: Type.String({ description: "The new message text (lightweight markdown by default)" }),
+		body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
 		html: Type.Optional(Type.Boolean({ description: "Treat 'body' as raw HTML instead of markdown" })),
 		account: AccountParam,
@@ -45,6 +46,7 @@ export const teamsUpdateMessageTool = {
 	promptSnippet: "Edit a message the user sent in Teams",
 	promptGuidelines: [
 		"Use teams_update_message to correct a message the user already sent, rather than deleting it and posting a replacement.",
+		CHAT_SHAPE_GUIDELINE,
 	],
 
 	async execute(

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/utils/chat-style.ts

@@ -0,0 +1,65 @@
+/**
+ * The shape of a Teams message.
+ *
+ * A chat bubble is read at a glance, on a phone, between two other things. The
+ * failure mode is well known and it is not a lack of language skill: the model
+ * writes a *document*. It opens with context, builds up to the point, and
+ * closes with a summary — so the reader has to hunt for the answer, which is
+ * exactly the "wall of text" people complain about.
+ *
+ * Telling the model to "be brief" does not fix it. Vague length advice is the
+ * weakest kind of formatting instruction; an explicit shape and a worked
+ * example are the strongest, and they have to sit where the message is being
+ * composed rather than in a document the model may or may not have loaded.
+ *
+ * So one shape, stated the same way in every place that matters:
+ *
+ *   - the `body` parameter description — in context at the moment of writing,
+ *     which is the highest-attention placement available,
+ *   - the per-tool guideline bullet — in context for the whole session, and
+ *     flat in the Guidelines list, so it has to name its tools,
+ *   - the skill and the listen-mode prompt — which carry the worked example
+ *     (`skills/teams-collaboration/SKILL.md`).
+ *
+ * Keeping it in one module is the point. Four tools used to carry their own
+ * copy of one sentence, they had drifted, and the sentence they shared was
+ * "three short paragraphs at most" — which permits prose, and got prose.
+ */
+
+/**
+ * What a message body is, and what shape it has.
+ *
+ * Used as the `body` parameter description on every tool that sends one, so it
+ * is read at the moment the text is written. Kept short on purpose: it is in
+ * the tool schema, and every tool in this package is in context at once.
+ */
+export const CHAT_MESSAGE_BODY_DESCRIPTION =
+	"Message text as lightweight markdown, in chat shape: the answer on the first line, then at most 5 short " +
+	"lines, `- ` bullets for anything enumerable, one idea per line. No greeting, no closing, no summary. " +
+	"Rendered: **bold**, *italic*, `code`, ~~struck~~, [label](url), `- ` bullets, `1. ` numbered, ``` fences. " +
+	"A `#` heading arrives as a bold line; tables are not rendered at all.";
+
+/**
+ * The same shape as one guideline bullet.
+ *
+ * `promptGuidelines` are appended flat to the system prompt's Guidelines
+ * section with no tool-name prefix, so this names every tool it applies to —
+ * otherwise the model cannot tell which "the message body" means. It stays on
+ * one line for the same reason: it is a bullet in someone else's list.
+ */
+export const CHAT_SHAPE_GUIDELINE =
+	"teams_send_chat_message, teams_send_channel_message, teams_reply_channel_message and teams_update_message " +
+	"write chat shape, not a document: the answer on the first line, at most 5 short lines, `- ` bullets for " +
+	"enumerable items, no greeting, no closing summary, no tables.";
+
+/**
+ * The shape as prose, for the listen-mode prompt.
+ *
+ * Listen mode is the case where this matters most: an answer that arrives
+ * unrequested has to be readable at a glance, because the recipient is not
+ * waiting for it and did not ask for it.
+ */
+export const CHAT_SHAPE_FOR_LISTEN_MODE =
+	"Format it as a chat bubble, not a document: the answer on the first line, at most 5 short lines, " +
+	"`- ` bullets for anything enumerable, no greeting and no closing. The recipient is not expecting this " +
+	"message, so it has to be readable at a glance.";

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;
 	});
 }
 
@@ -244,11 +308,39 @@ export function openMessages(
 // 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?
  *
@@ -275,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,
@@ -293,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,15 @@ import {
 	chatsToExamine,
 	createWatchState,
 	isUnread,
+	noteDeferral,
 	noteFailure,
 	noteSuccess,
 	noteWake,
 	openMessages,
 	pruneState,
+	settleChat,
 	shouldWake,
+	waitingCount,
 	wakesThisHour,
 	WATCH_MESSAGE_WINDOW,
 	type WatchState,
@@ -78,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 */
@@ -132,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[];
 }
 
@@ -143,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,
@@ -155,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.
@@ -173,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;
 		}
@@ -189,19 +212,33 @@ 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);
+		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
@@ -217,10 +254,10 @@ export async function runWatchTick(
 	}
 
 	// 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 };
 }
 
 // ---------------------------------------------------------------------------
@@ -301,6 +338,7 @@ export function startWatchLoop(options: WatchLoopOptions): WatchLoop {
 		intervalSeconds: watch.intervalSeconds,
 		wakesThisHour: 0,
 		trackedChats: 0,
+		waiting: 0,
 	};
 
 	const schedule = (delayMs: number) => {
@@ -346,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

@@ -16,6 +16,7 @@
  */
 
 import type { MessageSummary, SignedInUser } from "../types.ts";
+import { CHAT_SHAPE_FOR_LISTEN_MODE } from "../utils/chat-style.ts";
 import type { WatchEvent } from "./loop.ts";
 
 function senderName(message: MessageSummary): string {
@@ -114,9 +115,7 @@ export function composeWatchPrompt(event: WatchEvent, me?: SignedInUser): string
 			"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, " +
-			"bullets for anything enumerable, no tables. The recipient is not expecting this message, so it has " +
-			"to be readable at a glance.",
+		CHAT_SHAPE_FOR_LISTEN_MODE,
 		"",
 		"Do not react, do not touch other chats, and do not send anything to a channel.",
 	].join("\n");