@clawling/clawchat-plugin-openclaw 2026.10.7-2 → 2026.10.8-2

package/dist/src/runtime.js

@@ -30,12 +30,14 @@ import { createNotifySignalObserver, createProtocolControlHandler, createReconne
 import { clawChatDbPathForStateDir, getClawChatStore, makeOwnerProfilePersister, } from "./storage.js";
 import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.js";
 import { loadClawChatPromptMetadata, renderClawChatProfilePrompt, resolveSenderRelation, } from "./profile-prompt.js";
+import { buildNoteMemorySection } from "./note-injection.js";
+import { buildGroupCatchUp, CATCH_UP_FETCH_ROWS, DeliveredGroupMessages } from "./group-catch-up.js";
 import { refreshGroupProfile, syncFirstSeenClawChatProfiles } from "./profile-sync.js";
 import { pullGroupMetadata, pullOwnerMetadata } from "./clawchat-metadata.js";
 import { deleteClawChatMemoryFile, readClawChatMemoryFile } from "./clawchat-memory.js";
 import { registerMentionRosterResolver } from "./mention-autolink.js";
 import { clearClawChatPromptInjectionForSession, stageClawChatPromptInjection, } from "./prompt-injection.js";
-import { createGroupMessageCoalescer } from "./group-message-coalescer.js";
+import { createGroupMessageCoalescer, relabelCoalescedGroupBody } from "./group-message-coalescer.js";
 import { openclawLlmContextDebug } from "./llm-context-debug.js";
 import { GroupSettingsCache } from "./group-settings.js";
 import { PermissionCache } from "./permissions.js";
@@ -90,7 +92,6 @@ function activationBootstrapInFlightCount(accountId) {
 // hermes plugin's GROUP_SETTINGS_READY_TIMEOUT_SECONDS (5s).
 const GROUP_SETTINGS_READY_TIMEOUT_MS = 5_000;
 /** Number of recent group messages to prepend as context when the agent is @-mentioned. */
-const MENTION_CONTEXT_N = 10;
 const CLAWCHAT_MEMORY_ROOT_UNAVAILABLE = "ClawChat memory root unavailable: OpenClaw workspaceDir could not be resolved";
 const OPENCLAW_CONFIRM_SLASH_COMMANDS = new Set([
     "approve",
@@ -2472,12 +2473,27 @@ export async function startOpenclawClawlingGateway(params) {
                 ownerMetadata: promptMetadata.ownerMetadata,
             })
             : [];
+        const noteMemorySection = await buildNoteMemorySection({
+            memoryRoot,
+            chatType: promptChatType,
+            chatId: turn.peer.id,
+            senderId: turn.senderId,
+            senderIsOwner: senderRelation === "owner",
+            selfId: account.userId,
+            speakers: turn.peer.kind === "group"
+                ? (turn.groupMessages && turn.groupMessages.length > 0
+                    ? turn.groupMessages.map((message) => ({ id: message.senderId, name: message.senderName }))
+                    : [{ id: turn.senderId, name: turn.senderNickName }])
+                : [],
+            caps: { user: account.noteCapUser, group: account.noteCapGroup, turn: account.noteCapTurn },
+        });
         return renderClawChatProfilePrompt({
             basePrompt: turn.peer.kind === "group" ? getClawChatGroupPrompt() : getClawChatUserPrompt(),
             ...promptMetadata,
             ownerIdFallback: account.ownerUserId,
             currentAgentIdFallback: account.userId,
             groupParticipants,
+            noteMemorySection,
             turn: {
                 chatType: promptChatType,
                 chatId: turn.peer.id,
@@ -2521,6 +2537,100 @@ export async function startOpenclawClawlingGateway(params) {
     // coalesced batch's transcript ("Alice:" rather than "usr_…:") without
     // touching disk.
     const knownNicknames = new Map();
+    // Group message ids already handed to the agent, per chat (see group-catch-up.ts).
+    const deliveredGroupMessages = new DeliveredGroupMessages();
+    // One catch-up line: `Name (usr_…): text`, the name from the stored frame's
+    // nick_name unless that is just the id, else the cached nickname.
+    const formatCatchUpLine = (row) => {
+        const text = (row.text ?? "").trim() || "(empty message)";
+        let senderId = "";
+        let nickName = "";
+        try {
+            const frame = row.raw_json ? JSON.parse(row.raw_json) : null;
+            senderId = typeof frame?.sender?.id === "string" ? frame.sender.id : "";
+            nickName = typeof frame?.sender?.nick_name === "string" ? frame.sender.nick_name : "";
+        }
+        catch {
+            // A malformed stored frame still yields its text.
+        }
+        if (!senderId)
+            return text;
+        const name = (nickName && nickName !== senderId ? nickName : knownNicknames.get(senderId)) ?? "";
+        return name ? `${name} (${senderId}): ${text}` : `${senderId}: ${text}`;
+    };
+    // The sender id of a stored row whose frame carried no real nickname (its
+    // nick_name is missing or just the id), else "".
+    const bareSenderIdOfRow = (row) => {
+        try {
+            const frame = row.raw_json
+                ? JSON.parse(row.raw_json)
+                : null;
+            const id = typeof frame?.sender?.id === "string" ? frame.sender.id : "";
+            const nick = typeof frame?.sender?.nick_name === "string" ? frame.sender.nick_name : "";
+            return id && (!nick || nick === id) ? id : "";
+        }
+        catch {
+            return "";
+        }
+    };
+    // Last group-metadata pull made only to resolve names, per chat: a sender who
+    // can never be resolved (deleted account) must not refetch on every batch.
+    const nicknameRefreshAt = new Map();
+    const NICKNAME_REFRESH_COOLDOWN_MS = 60_000;
+    const NICKNAME_REFRESH_TIMEOUT_MS = 3_000;
+    // Fill knownNicknames for `ids` from ClawChat memory; if some are still
+    // missing in a group, pull the group's participants once (bounded, with a
+    // cooldown) and read again. Never throws: a name is a nicety, the turn is not.
+    const warmGroupNicknames = async (peer, ids) => {
+        if (peer.kind !== "group")
+            return;
+        try {
+            const memoryRoot = resolveMemoryRootForPeer(peer);
+            if (!memoryRoot)
+                return;
+            const wanted = Array.from(new Set(Array.from(ids).filter((id) => id && id !== account.userId)));
+            const missing = () => wanted.filter((id) => !knownNicknames.has(id));
+            const readCached = async () => {
+                for (const id of missing()) {
+                    const nickname = await cachedNicknameFor(memoryRoot, id);
+                    if (nickname && nickname !== id)
+                        knownNicknames.set(id, nickname);
+                }
+            };
+            await readCached();
+            if (missing().length === 0)
+                return;
+            const now = Date.now();
+            const last = nicknameRefreshAt.get(peer.id);
+            if (last !== undefined && now - last < NICKNAME_REFRESH_COOLDOWN_MS)
+                return;
+            nicknameRefreshAt.set(peer.id, now);
+            let timer;
+            await Promise.race([
+                refreshGroupProfile({
+                    platform: "openclaw",
+                    accountId,
+                    accountUserId: account.userId,
+                    accountOwnerUserId: account.ownerUserId,
+                    conversationId: peer.id,
+                    api: getConversationApiClient(),
+                    store: {},
+                    memoryRoot,
+                    log: { error: (message) => log?.error?.(`[${accountId}] ${message}`) },
+                }),
+                new Promise((resolve) => {
+                    timer = setTimeout(resolve, NICKNAME_REFRESH_TIMEOUT_MS);
+                }),
+            ]).finally(() => {
+                if (timer)
+                    clearTimeout(timer);
+            });
+            await readCached();
+        }
+        catch (err) {
+            log?.error?.(`[${accountId}] clawchat-plugin-openclaw group sender name lookup failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
     const withCachedGroupSenderNames = async (turn, memoryRoot) => {
         if (turn.peer.kind !== "group" || !memoryRoot)
             return turn;
@@ -2552,10 +2662,39 @@ export async function startOpenclawClawlingGateway(params) {
         const senderNickName = isBareId(turn.senderNickName, turn.senderId)
             ? (await lookup(turn.senderId)) ?? turn.senderNickName
             : turn.senderNickName;
+        // The wire carries no sender type, so a batch message from another agent
+        // (Hermes, a second OpenClaw…) would read as a person. users/<id>.md holds
+        // the backend's user type; this agent is always an agent.
+        const typeCache = new Map();
+        const lookupProfileType = async (userId) => {
+            if (userId === account.userId)
+                return "agent";
+            if (!typeCache.has(userId)) {
+                let profileType = null;
+                try {
+                    const userFile = await readClawChatMemoryFile(memoryRoot, { targetType: "user", targetId: userId });
+                    profileType = userFile.exists && userFile.metadata.profile_type ? userFile.metadata.profile_type : null;
+                }
+                catch {
+                    profileType = null;
+                }
+                typeCache.set(userId, profileType);
+            }
+            return typeCache.get(userId) ?? null;
+        };
         const groupMessages = turn.groupMessages
-            ? await Promise.all(turn.groupMessages.map(async (message) => isBareId(message.senderName, message.senderId)
-                ? { ...message, senderName: (await lookup(message.senderId)) ?? message.senderName }
-                : message))
+            ? await Promise.all(turn.groupMessages.map(async (message) => {
+                const named = isBareId(message.senderName, message.senderId)
+                    ? { ...message, senderName: (await lookup(message.senderId)) ?? message.senderName }
+                    : message;
+                const profileType = await lookupProfileType(message.senderId);
+                if (!profileType || profileType === named.senderProfileType)
+                    return named;
+                const senderRelation = profileType === "agent" && named.senderRelation === "peer_user"
+                    ? "peer_agent"
+                    : named.senderRelation;
+                return { ...named, senderProfileType: profileType, senderRelation };
+            }))
             : turn.groupMessages;
         return { ...turn, senderNickName, ...(groupMessages ? { groupMessages } : {}) };
     };
@@ -2897,32 +3036,55 @@ export async function startOpenclawClawlingGateway(params) {
                 log?.info?.(`[${accountId}] clawchat-plugin-openclaw coalesced group batch dropped at flush (now mention-only, no mention) chat_id=${turn.peer.id} msg=${turn.messageId}`);
                 return;
             }
+            const chatId = turn.peer.id;
+            const batchIds = new Set(turn.allMessageIds ?? [turn.messageId]);
+            const catchUpRows = turn.wasMentioned && store?.listRecentGroupMessages
+                ? store.listRecentGroupMessages("openclaw", accountId, chatId, CATCH_UP_FETCH_ROWS + batchIds.size) ?? []
+                : [];
+            // Ingest labels a batch from the in-memory nickname map, which is empty
+            // after a restart, and catch-up lines read the same map: resolve every
+            // sender named here before the turn goes out.
+            await warmGroupNicknames(turn.peer, [
+                ...(turn.groupMessages ?? [])
+                    .filter((message) => !message.senderName || message.senderName === message.senderId)
+                    .map((message) => message.senderId),
+                ...(!turn.senderNickName || turn.senderNickName === turn.senderId ? [turn.senderId] : []),
+                ...catchUpRows.map(bareSenderIdOfRow),
+            ]);
+            if (turn.groupMessages?.length) {
+                turn = {
+                    ...turn,
+                    rawBody: relabelCoalescedGroupBody(turn.rawBody, turn.groupMessages, (id) => knownNicknames.get(id)),
+                    groupMessages: turn.groupMessages.map((message) => {
+                        const known = message.senderName === message.senderId ? knownNicknames.get(message.senderId) : undefined;
+                        return known ? { ...message, senderName: known } : message;
+                    }),
+                };
+            }
+            if (turn.senderNickName === turn.senderId && knownNicknames.has(turn.senderId)) {
+                turn = { ...turn, senderNickName: knownNicknames.get(turn.senderId) };
+            }
+            // An @-mention adds the group messages this session has not been given
+            // since its last turn (e.g. ones a mention-only group held back), within
+            // delta-budget-chars. Every batch handed to the agent is recorded as
+            // delivered, so nothing it already has comes back. See group-catch-up.ts.
+            let catchUp = null;
             if (turn.wasMentioned && store?.listRecentGroupMessages) {
-                const chatId = turn.peer.id;
-                // Dedupe: exclude rows whose message_id belongs to the current batch/turn.
-                // For a coalesced multi-message turn this covers every constituent ID,
-                // not just the latest one (turn.messageId), so none of the batched
-                // messages appear twice — once in the coalesced body and once in the
-                // prepended "Prior group context" block.
-                const batchIds = new Set(turn.allMessageIds ?? [turn.messageId]);
-                // Overfetch so the batch's own just-stored messages don't crowd out the
-                // MENTION_CONTEXT_N prior rows: fetch batch-size extra rows, drop the
-                // batch members, then keep the most recent MENTION_CONTEXT_N survivors.
-                const priorRows = store.listRecentGroupMessages("openclaw", accountId, chatId, MENTION_CONTEXT_N + batchIds.size) ?? [];
-                const contextRows = priorRows
-                    .filter((row) => row.message_id != null && !batchIds.has(row.message_id))
-                    .slice(-MENTION_CONTEXT_N);
-                if (contextRows.length > 0) {
-                    const priorContextBody = [
-                        "Prior group context:",
-                        ...contextRows.map((row, i) => `[prior ${i + 1}] ${row.text ?? "(empty)"}`),
-                    ].join("\n");
-                    await dispatchTurnToAgent({
-                        ...turn,
-                        rawBody: `${priorContextBody}\n${turn.rawBody}`,
-                    });
-                    return;
-                }
+                const fetchLimit = CATCH_UP_FETCH_ROWS + batchIds.size;
+                catchUp = buildGroupCatchUp({
+                    chatId,
+                    rows: catchUpRows,
+                    fetchLimit,
+                    batchIds,
+                    delivered: deliveredGroupMessages,
+                    budgetChars: account.deltaBudgetChars,
+                    formatLine: formatCatchUpLine,
+                });
+            }
+            deliveredGroupMessages.remember(chatId, batchIds);
+            if (catchUp) {
+                await dispatchTurnToAgent({ ...turn, rawBody: `${catchUp}\n${turn.rawBody}` });
+                return;
             }
             await dispatchTurnToAgent(turn);
         },
@@ -3207,8 +3369,8 @@ export async function startOpenclawClawlingGateway(params) {
         })();
     });
     // `message.recall` — the sender withdrew a message. Erase our own ledger row
-    // so the "Prior group context" block above (MENTION_CONTEXT_N rows, no time
-    // predicate, no retention) can never read it back into a turn.
+    // so the mention catch-up above (unseen group messages, no time predicate,
+    // no retention) can never read it back into a turn.
     //
     // Ids only: the frame carries no content, and `payload.message_id` is the
     // server's `rcl:<target>` slot — the id to delete is `target_message_id`.

package/dist/src/storage.js

@@ -475,8 +475,8 @@ export class ClawChatStore {
      *
      * **The only DELETE in this store, and deliberately so.** There is no prune
      * and no retention on `clawchat_messages`: without this, a message recalled
-     * ninety seconds after it was sent stays one @-mention away from being read
-     * back aloud under "Prior group context" for as long as the group is quiet.
+     * ninety seconds after it was sent, before the agent was given it, stays
+     * one @-mention away from being read back in the mention catch-up.
      *
      * Scoped to `(platform, account_id)` so one account's recall cannot reach
      * another's rows, and matched on `message_id`, which seeks via the

package/openclaw.plugin.json

@@ -128,6 +128,10 @@
       "awarenessNote": { "type": "boolean" },
       "friendGreeting": { "type": "boolean" },
       "livewareSample": { "type": "boolean" },
+      "note-cap-user": { "type": "integer" },
+      "note-cap-group": { "type": "integer" },
+      "note-cap-turn": { "type": "integer" },
+      "delta-budget-chars": { "type": "integer" },
       "reconnect": {
         "type": "object",
         "additionalProperties": false,
@@ -202,6 +206,10 @@
             "awarenessNote": { "type": "boolean" },
             "friendGreeting": { "type": "boolean" },
             "livewareSample": { "type": "boolean" },
+            "note-cap-user": { "type": "integer" },
+            "note-cap-group": { "type": "integer" },
+            "note-cap-turn": { "type": "integer" },
+            "delta-budget-chars": { "type": "integer" },
             "reconnect": {
               "type": "object",
               "additionalProperties": false,
@@ -282,6 +290,10 @@
           "awarenessNote": { "type": "boolean" },
           "friendGreeting": { "type": "boolean" },
           "livewareSample": { "type": "boolean" },
+          "note-cap-user": { "type": "integer" },
+          "note-cap-group": { "type": "integer" },
+          "note-cap-turn": { "type": "integer" },
+          "delta-budget-chars": { "type": "integer" },
           "reconnect": {
             "type": "object",
             "additionalProperties": false,
@@ -356,6 +368,10 @@
                 "awarenessNote": { "type": "boolean" },
                 "friendGreeting": { "type": "boolean" },
                 "livewareSample": { "type": "boolean" },
+                "note-cap-user": { "type": "integer" },
+                "note-cap-group": { "type": "integer" },
+                "note-cap-turn": { "type": "integer" },
+                "delta-budget-chars": { "type": "integer" },
                 "reconnect": {
                   "type": "object",
                   "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clawling/clawchat-plugin-openclaw",
-  "version": "2026.10.7-2",
+  "version": "2026.10.8-2",
   "description": "OpenClaw ClawChat channel plugin",
   "license": "MIT",
   "author": "CLAWLING PTE. LTD.",

package/src/clawchat-metadata.ts

@@ -293,10 +293,17 @@ export async function pullGroupMetadata(params: {
         targetType: "user",
         targetId: mapped.userId,
       });
-      if (existing.exists) continue;
+      // A cached file is kept as is, except that one without profile_type
+      // (written before types were recorded) gets just that field filled in:
+      // without it the prompt lists a peer agent as a person.
+      if (existing.exists && existing.metadata.profile_type) continue;
       if (!getUser) throw new Error("ClawChat participant metadata pull requires getUserProfile");
       const profile = await getUser(mapped.userId);
-      const metadata = userMetadataFromProfile(profile, mapped.userId);
+      const fetched = userMetadataFromProfile(profile, mapped.userId);
+      if (existing.exists && !fetched.profile_type) continue;
+      const metadata = existing.exists
+        ? { ...existing.metadata, profile_type: fetched.profile_type! }
+        : fetched;
       await writeClawChatMetadata(
         params.memoryRoot,
         { targetType: "user", targetId: mapped.userId },

package/src/config.ts

@@ -120,6 +120,11 @@ export type OpenclawClawlingAccountConfig = {
   friendGreeting?: boolean;
   /** Auto-install the Liveware Sample demo app when no liveware app is registered (default true). */
   livewareSample?: boolean;
+  /** Shared ClawChat session / note keys (hyphenated; see SESSION_INT_KEYS). */
+  "note-cap-user"?: number;
+  "note-cap-group"?: number;
+  "note-cap-turn"?: number;
+  "delta-budget-chars"?: number;
   reconnect?: OpenclawClawlingReconnectConfig;
   heartbeat?: OpenclawClawlingHeartbeatConfig;
   ack?: OpenclawClawlingAckConfig;
@@ -181,6 +186,10 @@ export const openclawClawlingAccountConfigSchema = {
     awarenessNote: { type: "boolean" },
     friendGreeting: { type: "boolean" },
     livewareSample: { type: "boolean" },
+    "note-cap-user": { type: "integer" },
+    "note-cap-group": { type: "integer" },
+    "note-cap-turn": { type: "integer" },
+    "delta-budget-chars": { type: "integer" },
     reconnect: {
       type: "object",
       additionalProperties: false,
@@ -320,6 +329,14 @@ export type ResolvedOpenclawClawlingAccount = {
   awarenessNote: boolean;
   friendGreeting: boolean;
   livewareSample: boolean;
+  /** `note-cap-user`: characters of one person's note shown in a turn. */
+  noteCapUser: number;
+  /** `note-cap-group`: characters of the group's note shown in a group turn. */
+  noteCapGroup: number;
+  /** `note-cap-turn`: characters of all notes shown in one turn together. */
+  noteCapTurn: number;
+  /** `delta-budget-chars`: characters of unseen group messages an @-mention adds. */
+  deltaBudgetChars: number;
   allowFrom: string[];
   reconnect: Required<OpenclawClawlingReconnectConfig>;
   heartbeat: Required<OpenclawClawlingHeartbeatConfig>;
@@ -564,6 +581,31 @@ export function effectiveOutputVisibility(
     ?? "normal";
 }
 
+/**
+ * Session / note keys shared with the other ClawChat agent channels (same
+ * hyphenated names, meaning and factory values as the Hermes plugin's
+ * `SESSION_INT_KEYS`). An out-of-range value is clamped to the nearest bound,
+ * a non-number falls back to the factory value. Every key here has a reader;
+ * the shared keys this plugin has no use for are listed in
+ * docs/clawchat-plugin-openclaw.md with the reason.
+ *   key -> [factory, minimum, maximum]
+ */
+export const SESSION_INT_KEYS = {
+  "note-cap-user": [1500, 300, 6000],
+  "note-cap-group": [2000, 300, 8000],
+  "note-cap-turn": [4000, 1000, 16000],
+  "delta-budget-chars": [8000, 2000, 32000],
+} as const satisfies Record<string, readonly [number, number, number]>;
+
+function readSessionInt(channel: Record<string, unknown>, key: keyof typeof SESSION_INT_KEYS): number {
+  const [factory, minimum, maximum] = SESSION_INT_KEYS[key];
+  const raw = channel[key];
+  const parsed =
+    typeof raw === "number" ? raw : typeof raw === "string" && raw.trim() ? Number(raw.trim()) : Number.NaN;
+  if (!Number.isFinite(parsed)) return factory;
+  return Math.max(minimum, Math.min(maximum, Math.trunc(parsed)));
+}
+
 function readReconnect(raw: unknown): Required<OpenclawClawlingReconnectConfig> {
   const s = raw && typeof raw === "object" ? (raw as Record<string, unknown>) : {};
   return {
@@ -693,6 +735,10 @@ export function resolveOpenclawClawlingAccount(
     awarenessNote,
     friendGreeting,
     livewareSample,
+    noteCapUser: readSessionInt(channel, "note-cap-user"),
+    noteCapGroup: readSessionInt(channel, "note-cap-group"),
+    noteCapTurn: readSessionInt(channel, "note-cap-turn"),
+    deltaBudgetChars: readSessionInt(channel, "delta-budget-chars"),
     allowFrom: [],
     reconnect: readReconnect(channel.reconnect),
     heartbeat: readHeartbeat(channel.heartbeat),

package/src/group-catch-up.ts

@@ -0,0 +1,112 @@
+/**
+ * What an @-mention adds in front of a group turn: the group messages this
+ * agent's session has not been given since its last turn.
+ *
+ * Every group batch the plugin hands to the host is recorded as delivered
+ * (per chat, bounded). On a mention, the ledger's recent group messages minus
+ * the delivered ones, the agent's own replies and the batch itself are the
+ * catch-up — e.g. messages a mention-only group held back. It is bounded by
+ * the shared `delta-budget-chars` key (characters, newest kept first); the
+ * unseen messages that do not fit are counted in one closing line, and are
+ * recorded as delivered with the rest, so a later mention does not bring them
+ * back out of order. Same rule as the Hermes plugin's shared group sessions.
+ *
+ * The delivered record is in memory: after a gateway restart the first
+ * mention may repeat up to that budget of messages the session already has.
+ */
+
+/** How far back the ledger is read to find unseen messages (one row per message). */
+export const CATCH_UP_FETCH_ROWS = 500;
+/** Per group, how many delivered message ids are remembered. */
+export const DELIVERED_GROUP_IDS_MAX = 500;
+
+export const GROUP_UNSEEN_HEADER =
+  "[ClawChat group messages you have not seen yet, oldest first. " +
+  "Context only; the new messages follow.]";
+
+export function groupUnseenLeftOutLine(count: string): string {
+  return (
+    `[${count} earlier unseen group messages were left out for length. If you ` +
+    "need them, ask in the group; the group's note (clawchat_memory_read) " +
+    "holds what was saved about it.]"
+  );
+}
+
+export class DeliveredGroupMessages {
+  private readonly byChat = new Map<string, Set<string>>();
+
+  constructor(private readonly max = DELIVERED_GROUP_IDS_MAX) {}
+
+  remember(chatId: string, messageIds: Iterable<string | null | undefined>): void {
+    let delivered = this.byChat.get(chatId);
+    if (!delivered) {
+      delivered = new Set();
+      this.byChat.set(chatId, delivered);
+    }
+    for (const id of messageIds) {
+      if (!id) continue;
+      delivered.delete(id); // re-insert at the end (most recent)
+      delivered.add(id);
+    }
+    while (delivered.size > this.max) {
+      const oldest = delivered.values().next().value as string;
+      delivered.delete(oldest);
+    }
+  }
+
+  has(chatId: string, messageId: string): boolean {
+    return this.byChat.get(chatId)?.has(messageId) ?? false;
+  }
+}
+
+export type CatchUpRow = {
+  message_id: string | null;
+  direction?: string | null;
+  text?: string | null;
+};
+
+/**
+ * The catch-up text (or null when nothing is unseen) for `rows` (oldest
+ * first, as read from the ledger with `fetchLimit`). Records every unseen row
+ * as delivered.
+ */
+export function buildGroupCatchUp<Row extends CatchUpRow>(params: {
+  chatId: string;
+  rows: Row[];
+  fetchLimit: number;
+  batchIds: Set<string>;
+  delivered: DeliveredGroupMessages;
+  budgetChars: number;
+  formatLine: (row: Row) => string;
+}): string | null {
+  const { chatId, rows, batchIds, delivered, budgetChars } = params;
+  const windowFull = rows.length >= params.fetchLimit;
+  const unseen = rows.filter(
+    (row) =>
+      row.message_id != null &&
+      row.direction !== "outbound" &&
+      !batchIds.has(row.message_id) &&
+      !delivered.has(chatId, row.message_id),
+  );
+  if (unseen.length === 0) return null;
+  delivered.remember(chatId, unseen.map((row) => row.message_id));
+  const kept: string[] = [];
+  let used = 0;
+  for (let index = unseen.length - 1; index >= 0; index -= 1) {
+    // newest first, so the budget keeps the latest
+    const line = params.formatLine(unseen[index]!);
+    const cost = line.length + (kept.length > 0 ? 1 : 0);
+    if (used + cost > budgetChars) {
+      if (kept.length === 0) kept.push(`${line.slice(0, Math.max(0, budgetChars - 1))}…`);
+      break;
+    }
+    kept.push(line);
+    used += cost;
+  }
+  const leftOut = unseen.length - kept.length;
+  const lines = [GROUP_UNSEEN_HEADER, ...kept.reverse()];
+  if (leftOut > 0 || windowFull) {
+    lines.push(groupUnseenLeftOutLine(windowFull ? `${leftOut}+` : String(leftOut)));
+  }
+  return lines.join("\n");
+}

package/src/group-message-coalescer.ts

@@ -93,6 +93,38 @@ export function formatCoalescedGroupBody(
   ].join("\n");
 }
 
+/**
+ * Relabel a coalesced body's `[message N] <sender>:` lines whose sender was
+ * still a bare id when the batch was built (ingest labels synchronously from
+ * an in-memory nickname map, which is empty right after a restart). Only the
+ * label line of each message, in order, is touched; bodies are never rewritten.
+ */
+export function relabelCoalescedGroupBody(
+  rawBody: string,
+  messages: Pick<CoalescedGroupPromptMessage, "senderId" | "senderName">[],
+  nameFor: (senderId: string) => string | undefined,
+): string {
+  const lines = rawBody.split("\n");
+  let from = 0;
+  messages.forEach((message, index) => {
+    const prefix = `[message ${index + 1}] ${formatField(message.senderId)}:`;
+    let at = -1;
+    for (let i = from; i < lines.length; i += 1) {
+      if (lines[i]!.startsWith(`[message ${index + 1}] `)) {
+        at = i;
+        break;
+      }
+    }
+    if (at < 0) return;
+    from = at + 1;
+    if (message.senderName && message.senderName !== message.senderId) return;
+    const name = nameFor(message.senderId);
+    if (!name || name === message.senderId || !lines[at]!.startsWith(prefix)) return;
+    lines[at] = `[message ${index + 1}] ${formatField(name)}:${lines[at]!.slice(prefix.length)}`;
+  });
+  return lines.join("\n");
+}
+
 function groupMessageForPrompt(turn: CoalescableGroupTurn): CoalescedGroupPromptMessage {
   return {
     messageId: turn.messageId,