@kyan-du/agent-wechat-openclaw 0.12.0-next.0 → 0.13.0

package/dist/index.js

@@ -1102,8 +1102,10 @@ var DEFAULT_CATCH_UP_MAX_AGE_MS = 5 * 6e4;
 var DEFAULT_CATCH_UP_CHAT_BUDGET = 5;
 var DEFAULT_MEDIA_PART_DELAY_MS = 750;
 var DEFAULT_ACCOUNT_ID = "default";
+var OPENCLAW_CHANNEL_ID = "agent-wechat";
 function resolveWeChatAccount(cfg, accountId) {
-  const wechat = cfg.channels?.wechat;
+  const channels = cfg.channels;
+  const wechat = channels?.[OPENCLAW_CHANNEL_ID] ?? channels?.wechat;
   if (!wechat?.serverUrl) return null;
   return {
     accountId: accountId ?? DEFAULT_ACCOUNT_ID,
@@ -5592,6 +5594,248 @@ function selectCatchUpMessages(messages, limits, mode = "latest") {
   };
 }
 
+// src/monitor-cursor.ts
+function cursorMessageKey(message) {
+  return `${message.serverId ?? ""}:${message.timestamp}:${message.type}:${message.sender ?? ""}:${message.content ?? ""}`;
+}
+function markEqualCursorUnreadHandled(chatId, message, equalCursorUnreadHandled) {
+  if (message === void 0) return;
+  equalCursorUnreadHandled.set(chatId, {
+    localId: message.localId,
+    messageKey: cursorMessageKey(message)
+  });
+}
+function markCursorMessagesHandled(chatId, messages, equalCursorUnreadHandled) {
+  if (messages.length === 0) return void 0;
+  const cursorMessage = messages.reduce(
+    (latest, message) => message.localId > latest.localId ? message : latest
+  );
+  markEqualCursorUnreadHandled(chatId, cursorMessage, equalCursorUnreadHandled);
+  return cursorMessage.localId;
+}
+function selectCursorMessages(chatId, chat, messages, lastSeenId, equalCursorUnreadHandled, startupBaseline, generationResetConfirmed = false) {
+  const firstPoll = !lastSeenId.has(chatId);
+  const prevLastSeen = lastSeenId.get(chatId) ?? 0;
+  const sorted = [...messages].sort((a, b) => a.localId - b.localId);
+  const baselineActive = startupBaseline !== void 0 && (firstPoll || prevLastSeen < startupBaseline.localId);
+  if (baselineActive) {
+    const baselineRow = sorted.find((message) => message.localId === startupBaseline.localId);
+    const generationReset = sorted.length > 0 && typeof chat.lastMsgLocalId === "number" && chat.lastMsgLocalId <= startupBaseline.localId && (baselineRow === void 0 && sorted.every((message) => message.localId < startupBaseline.localId) || baselineRow !== void 0 && startupBaseline.messageKey !== void 0 && cursorMessageKey(baselineRow) !== startupBaseline.messageKey);
+    if (generationReset || generationResetConfirmed) {
+      return {
+        firstPoll,
+        prevLastSeen,
+        messages: sorted,
+        generationReset: true
+      };
+    }
+    const live = sorted.filter(
+      (message) => message.localId > startupBaseline.localId || message.localId === startupBaseline.localId && startupBaseline.messageKey !== void 0 && cursorMessageKey(message) !== startupBaseline.messageKey
+    );
+    const seedLastSeen = sorted.filter((message) => message.localId <= startupBaseline.localId).at(-1)?.localId;
+    return {
+      firstPoll,
+      prevLastSeen,
+      messages: live,
+      seedLastSeen
+    };
+  }
+  if (firstPoll) {
+    const unread2 = chat.unreadCount ?? 0;
+    if (unread2 > 0 && unread2 < sorted.length) {
+      return {
+        firstPoll,
+        prevLastSeen,
+        messages: sorted.slice(-unread2),
+        seedLastSeen: sorted[sorted.length - unread2 - 1].localId
+      };
+    }
+    if (unread2 >= sorted.length) {
+      return { firstPoll, prevLastSeen, messages: sorted };
+    }
+    return {
+      firstPoll,
+      prevLastSeen,
+      messages: [],
+      seedLastSeen: sorted[sorted.length - 1]?.localId
+    };
+  }
+  const newer = sorted.filter((m) => m.localId > prevLastSeen);
+  if (newer.length > 0) {
+    return { firstPoll, prevLastSeen, messages: newer };
+  }
+  const unread = chat.unreadCount ?? 0;
+  const handled = equalCursorUnreadHandled.get(chatId);
+  const equalCursorRows = sorted.filter((message) => message.localId === prevLastSeen);
+  const equalIdGenerationReset = unread > 0 && chat.lastMsgLocalId === prevLastSeen && sorted.every((message) => message.localId <= prevLastSeen) && equalCursorRows.length === 1 && handled?.localId === prevLastSeen && handled.messageKey !== cursorMessageKey(equalCursorRows[0]);
+  const lowerIdGenerationReset = unread > 0 && sorted.length > 0 && sorted.every((message) => message.localId < prevLastSeen) && typeof chat.lastMsgLocalId === "number" && chat.lastMsgLocalId < prevLastSeen;
+  if (lowerIdGenerationReset || equalIdGenerationReset || generationResetConfirmed) {
+    return {
+      firstPoll,
+      prevLastSeen,
+      messages: sorted,
+      generationReset: true
+    };
+  }
+  if (unread <= 0) {
+    return { firstPoll, prevLastSeen, messages: [] };
+  }
+  const unreadSuffix = sorted.slice(-Math.min(unread, sorted.length));
+  const equalCursorUnread = unreadSuffix.filter((m) => m.localId === prevLastSeen);
+  const recoverable = equalCursorUnread.length === 1 && chat.lastMsgLocalId === prevLastSeen && (handled?.localId !== prevLastSeen || handled.messageKey !== cursorMessageKey(equalCursorUnread[0]));
+  return {
+    firstPoll,
+    prevLastSeen,
+    messages: recoverable ? equalCursorUnread : []
+  };
+}
+function seedStartupBaselineFromChat(chat) {
+  return typeof chat.lastMsgLocalId === "number" && chat.lastMsgLocalId > 0 ? { localId: chat.lastMsgLocalId } : void 0;
+}
+function enrichStartupBaselineFromMessages(baseline, messages) {
+  if (baseline === void 0 || baseline.messageKey !== void 0) return baseline;
+  const match = messages.find((message) => message.localId === baseline.localId);
+  return match ? { ...baseline, messageKey: cursorMessageKey(match) } : baseline;
+}
+function selectMessagesHandledAfterDispatch(messages, successfulSegmentLastLocalIds) {
+  if (successfulSegmentLastLocalIds.length === 0) return [];
+  const lastHandled = Math.max(...successfulSegmentLastLocalIds);
+  return messages.filter((message) => message.localId <= lastHandled);
+}
+
+// src/monitor-scan.ts
+var MONITOR_CHAT_PAGE_LIMIT = 100;
+var MONITOR_MESSAGE_PAGE_LIMIT = 200;
+var DEFAULT_MESSAGE_PAGE_BUDGET = 50;
+var DEFAULT_INITIAL_CHAT_PAGE_BUDGET = 100;
+async function listInitialMonitorChatSnapshot(client, state, pageBudget = DEFAULT_INITIAL_CHAT_PAGE_BUDGET) {
+  if (state.initialScanComplete) return [];
+  const chats = [];
+  let cursor;
+  for (let pages = 0; pages < pageBudget; pages += 1) {
+    const page = await client.listChatsPage(MONITOR_CHAT_PAGE_LIMIT, cursor);
+    chats.push(...page.items);
+    cursor = page.nextCursor;
+    if (!cursor) {
+      state.initialScanComplete = true;
+      state.cursor = void 0;
+      return chats;
+    }
+  }
+  throw new Error(`initial chat snapshot exceeded ${pageBudget} pages`);
+}
+async function listNextMonitorChatPage(client, state) {
+  const isInitialSnapshot = !state.initialScanComplete;
+  const page = await client.listChatsPage(MONITOR_CHAT_PAGE_LIMIT, state.cursor);
+  state.cursor = page.nextCursor;
+  if (!page.nextCursor) {
+    state.initialScanComplete = true;
+    state.cursor = void 0;
+  }
+  return { chats: page.items, isInitialSnapshot };
+}
+function hasReachedStableMessageBoundary(messages, chat, firstPoll, prevLastSeen, startupBaseline) {
+  if (messages.length === 0) return false;
+  const sorted = [...messages].sort((a, b) => a.localId - b.localId);
+  if (startupBaseline !== void 0 && (firstPoll || prevLastSeen < startupBaseline.localId)) {
+    if (startupBaseline.localId <= 0) return true;
+    if (sorted.some((message) => message.localId === startupBaseline.localId)) return true;
+    return false;
+  }
+  if (firstPoll) {
+    const unread2 = chat.unreadCount ?? 0;
+    if (unread2 > 0) return messages.length >= unread2 + 1;
+    return true;
+  }
+  if (sorted.some((message) => message.localId <= prevLastSeen)) return true;
+  const unread = chat.unreadCount ?? 0;
+  return unread > 0 && messages.length >= unread;
+}
+function detectsGenerationReset(messages, chat, firstPoll, prevLastSeen, startupBaseline, handledCursor) {
+  if (messages.length === 0 || typeof chat.lastMsgLocalId !== "number") return false;
+  const boundary = startupBaseline !== void 0 && (firstPoll || prevLastSeen < startupBaseline.localId) ? startupBaseline : handledCursor?.localId === prevLastSeen ? handledCursor : void 0;
+  const boundaryLocalId = boundary?.localId ?? prevLastSeen;
+  if (chat.lastMsgLocalId < boundaryLocalId) return true;
+  if (chat.lastMsgLocalId !== boundaryLocalId || boundary?.messageKey === void 0) return false;
+  const equalRow = messages.find((message) => message.localId === boundaryLocalId);
+  return equalRow !== void 0 && cursorMessageKey(equalRow) !== boundary.messageKey;
+}
+function generationBoundaryIndex(messages) {
+  for (let index = 1; index < messages.length; index += 1) {
+    if (messages[index].localId >= messages[index - 1].localId) return index;
+  }
+  return void 0;
+}
+function shouldProbeGenerationReset(messages, chat, firstPoll, prevLastSeen, startupBaseline, handledCursor) {
+  if (typeof chat.lastMsgLocalId !== "number") return false;
+  const boundary = startupBaseline !== void 0 && (firstPoll || prevLastSeen < startupBaseline.localId) ? startupBaseline : handledCursor?.localId === prevLastSeen ? handledCursor : void 0;
+  if (boundary === void 0 || chat.lastMsgLocalId > boundary.localId) return false;
+  return !messages.some((message) => message.localId === boundary.localId);
+}
+async function listMessagesForMonitorCursor(client, chatId, options) {
+  const pageBudget = options.pageBudget ?? DEFAULT_MESSAGE_PAGE_BUDGET;
+  const messages = [...options.continuation?.messages ?? []];
+  let cursor = options.continuation?.cursor;
+  let generationReset = options.continuation?.generationReset ?? false;
+  let pagesScanned = 0;
+  while (pagesScanned < pageBudget) {
+    const page = await client.listMessagesPage(chatId, MONITOR_MESSAGE_PAGE_LIMIT, cursor);
+    pagesScanned += 1;
+    messages.push(...page.items);
+    cursor = page.nextCursor;
+    generationReset ||= detectsGenerationReset(
+      messages,
+      options.chat,
+      options.firstPoll,
+      options.prevLastSeen,
+      options.startupBaseline,
+      options.handledCursor
+    );
+    if (generationReset) {
+      const boundaryIndex = generationBoundaryIndex(messages);
+      if (boundaryIndex !== void 0 || !cursor) {
+        return {
+          messages: boundaryIndex === void 0 ? messages : messages.slice(0, boundaryIndex),
+          complete: true,
+          nextCursor: void 0,
+          pagesScanned,
+          generationReset: true
+        };
+      }
+      continue;
+    }
+    const probingReset = shouldProbeGenerationReset(
+      messages,
+      options.chat,
+      options.firstPoll,
+      options.prevLastSeen,
+      options.startupBaseline,
+      options.handledCursor
+    );
+    if (!cursor || !probingReset && hasReachedStableMessageBoundary(
+      messages,
+      options.chat,
+      options.firstPoll,
+      options.prevLastSeen,
+      options.startupBaseline
+    )) {
+      return {
+        messages,
+        complete: true,
+        nextCursor: void 0,
+        pagesScanned
+      };
+    }
+  }
+  return {
+    messages,
+    complete: false,
+    nextCursor: cursor,
+    pagesScanned,
+    generationReset: generationReset || void 0
+  };
+}
+
 // src/outbound.ts
 import { randomUUID } from "node:crypto";
 async function sendLogicalMediaTask(opts) {
@@ -5623,6 +5867,255 @@ async function sendLogicalMediaTask(opts) {
   return requestId;
 }
 
+// src/monitor-retry.ts
+import {
+  existsSync,
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+  fsyncSync
+} from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+var MAX_PENDING_RESET_CHATS = 100;
+var MAX_PENDING_RESET_MESSAGES = 1e4;
+var MAX_RESET_RETRY_DELAY_MS = 6e4;
+var PendingRetryStateError = class extends Error {
+  code;
+  constructor(message, code) {
+    super(message);
+    this.name = "PendingRetryStateError";
+    this.code = code;
+  }
+};
+function retryStorePath(accountId, stateDir) {
+  const root = stateDir ?? process.env.OPENCLAW_STATE_DIR?.trim() ?? join(homedir(), ".openclaw");
+  const safeAccount = accountId.replace(/[^A-Za-z0-9._-]/g, "_");
+  return join(root, "wechat", `monitor-retry-${safeAccount}.json`);
+}
+function quarantinePath(path) {
+  return `${path}.corrupt`;
+}
+function blockerPath(path) {
+  return `${path}.blocked`;
+}
+function syncPath(path) {
+  const fd = openSync(path, "r");
+  try {
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+}
+function syncParent(path) {
+  syncPath(dirname(path));
+}
+function isStringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === "string");
+}
+function isFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+function validateMessage(message) {
+  if (message === null || typeof message !== "object") return false;
+  const row = message;
+  return Number.isSafeInteger(row.localId) && typeof row.chatId === "string" && Number.isSafeInteger(row.type) && typeof row.timestamp === "string" && (row.serverId === void 0 || Number.isSafeInteger(row.serverId)) && (row.content === void 0 || typeof row.content === "string") && (row.sender === void 0 || typeof row.sender === "string") && (row.isSelf === void 0 || typeof row.isSelf === "boolean") && (row.isMentioned === void 0 || typeof row.isMentioned === "boolean");
+}
+function validateChat(chat) {
+  if (chat === null || typeof chat !== "object") return false;
+  const row = chat;
+  return typeof row.id === "string" && typeof row.name === "string" && Number.isSafeInteger(row.unreadCount) && typeof row.isGroup === "boolean" && (row.username === void 0 || typeof row.username === "string") && (row.lastMsgLocalId === void 0 || Number.isSafeInteger(row.lastMsgLocalId)) && (row.remark === void 0 || typeof row.remark === "string") && (row.members === void 0 || isStringArray(row.members));
+}
+function validateEntries(entries) {
+  if (entries.length > MAX_PENDING_RESET_CHATS) {
+    throw new PendingRetryStateError("WeChat pending retry chat capacity exceeded", "RETRY_CAPACITY");
+  }
+  let total = 0;
+  for (const entry of entries) {
+    if (!Array.isArray(entry) || typeof entry[0] !== "string") {
+      throw new PendingRetryStateError("WeChat retry state entry is invalid", "RETRY_STATE_CORRUPT");
+    }
+    const pending = entry[1];
+    if (pending?.readyForDispatch !== true || !validateChat(pending.chat) || !Array.isArray(pending.messages) || !pending.messages.every(validateMessage) || pending.generationReset !== void 0 && typeof pending.generationReset !== "boolean" || pending.retryCount !== void 0 && !Number.isSafeInteger(pending.retryCount) || pending.nextRetryAt !== void 0 && !isFiniteNumber(pending.nextRetryAt) || pending.createdAt !== void 0 && !isFiniteNumber(pending.createdAt)) {
+      throw new PendingRetryStateError("WeChat pending retry payload is invalid", "RETRY_STATE_CORRUPT");
+    }
+    total += pending.messages.length;
+  }
+  if (total > MAX_PENDING_RESET_MESSAGES) {
+    throw new PendingRetryStateError("WeChat pending retry message capacity exceeded", "RETRY_CAPACITY");
+  }
+}
+function loadPendingResetRetries(accountId, stateDir) {
+  const path = retryStorePath(accountId, stateDir);
+  const blocked = blockerPath(path);
+  if (existsSync(blocked)) {
+    let quarantine = quarantinePath(path);
+    try {
+      const marker = JSON.parse(readFileSync(blocked, "utf8"));
+      if (typeof marker.quarantine === "string") quarantine = marker.quarantine;
+    } catch {
+    }
+    throw new PendingRetryStateError(
+      `WeChat retry recovery is blocked by ${blocked}. Reconcile ${quarantine}, then explicitly remove the blocker to resume.`,
+      "RETRY_STATE_BLOCKED"
+    );
+  }
+  if (!existsSync(path)) return /* @__PURE__ */ new Map();
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8"));
+    if (raw.version !== 1 || !Array.isArray(raw.entries)) {
+      throw new PendingRetryStateError("WeChat retry state schema is invalid", "RETRY_STATE_CORRUPT");
+    }
+    const entries = raw.entries;
+    validateEntries(entries);
+    return new Map(entries);
+  } catch (error) {
+    const quarantine = quarantinePath(path);
+    const blocked2 = blockerPath(path);
+    try {
+      rmSync(quarantine, { force: true });
+      renameSync(path, quarantine);
+      writeFileSync(blocked2, JSON.stringify({ version: 1, quarantine }), { mode: 384 });
+      syncPath(blocked2);
+      syncParent(path);
+    } catch (quarantineError) {
+      throw new PendingRetryStateError(
+        `WeChat retry state is unreadable at ${path}; quarantine failed (${String(quarantineError)}). Stop the channel and move this file aside manually.`,
+        "RETRY_STATE_CORRUPT"
+      );
+    }
+    throw new PendingRetryStateError(
+      `WeChat retry state was quarantined to ${quarantine} and blocked by ${blocked2}. Inspect/restore the quarantine, then explicitly remove the blocker to resume or discard after reconciliation. Cause: ${String(error)}`,
+      "RETRY_STATE_CORRUPT"
+    );
+  }
+}
+function persistPendingResetRetries(accountId, pending, stateDir) {
+  const path = retryStorePath(accountId, stateDir);
+  const entries = [...pending.entries()].filter(([, value]) => value.readyForDispatch);
+  validateEntries(entries);
+  if (entries.length === 0) {
+    if (!existsSync(path)) return;
+    rmSync(path, { force: true });
+    if (existsSync(dirname(path))) syncParent(path);
+    return;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  const temp = `${path}.tmp-${process.pid}`;
+  writeFileSync(temp, JSON.stringify({ version: 1, entries }), { mode: 384 });
+  syncPath(temp);
+  renameSync(temp, path);
+  syncParent(path);
+}
+function persist(state) {
+  state.persist?.();
+}
+function mergeMessages(current, incoming) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const message of [...current, ...incoming]) {
+    merged.set(cursorMessageKey(message), message);
+  }
+  return [...merged.values()].sort((a, b) => a.localId - b.localId);
+}
+function assertStateCapacity(pending) {
+  validateEntries([...pending.entries()]);
+}
+function trimPendingResetRetries(state) {
+  assertStateCapacity(state.pendingMessageScans);
+  persist(state);
+}
+function clearPendingResetRetry(state, chatId) {
+  if (state.pendingMessageScans.delete(chatId)) persist(state);
+}
+function queueResetGenerationRetry(state, chatId, chat, messages, now = Date.now()) {
+  const existing = state.pendingMessageScans.get(chatId);
+  const merged = mergeMessages(existing?.messages ?? [], messages);
+  const next = {
+    chat,
+    messages: merged,
+    generationReset: true,
+    readyForDispatch: true,
+    retryCount: existing?.retryCount ?? 0,
+    nextRetryAt: existing?.nextRetryAt ?? now,
+    createdAt: existing?.createdAt ?? now
+  };
+  const projected = new Map(state.pendingMessageScans);
+  projected.set(chatId, next);
+  assertStateCapacity(projected);
+  state.pendingMessageScans.delete(chatId);
+  state.pendingMessageScans.set(chatId, next);
+  persist(state);
+}
+function mergePendingResetMessages(state, chatId, chat, messages) {
+  const pending = state.pendingMessageScans.get(chatId);
+  if (!pending?.readyForDispatch) return messages;
+  const merged = mergeMessages(pending.messages, messages);
+  const projected = new Map(state.pendingMessageScans);
+  projected.set(chatId, { ...pending, chat, messages: merged });
+  assertStateCapacity(projected);
+  state.pendingMessageScans.set(chatId, { ...pending, chat, messages: merged });
+  persist(state);
+  return merged;
+}
+function recordResetRetryFailure(state, chatId, now = Date.now()) {
+  const pending = state.pendingMessageScans.get(chatId);
+  if (!pending?.readyForDispatch) return;
+  const retryCount = (pending.retryCount ?? 0) + 1;
+  const delay = Math.min(MAX_RESET_RETRY_DELAY_MS, 1e3 * 2 ** Math.min(retryCount - 1, 6));
+  state.pendingMessageScans.set(chatId, {
+    ...pending,
+    retryCount,
+    nextRetryAt: now + delay
+  });
+  persist(state);
+}
+function monitorChatsToProcess(chats, state, now = Date.now()) {
+  const result = /* @__PURE__ */ new Map();
+  for (const pending of state.pendingMessageScans.values()) {
+    const chatId = pending.chat.username ?? pending.chat.id;
+    if ((pending.nextRetryAt ?? 0) <= now) result.set(chatId, pending.chat);
+  }
+  for (const chat of chats) {
+    const chatId = chat.username ?? chat.id;
+    if (chat.unreadCount > 0 || state.pendingMessageScans.has(chatId)) result.set(chatId, chat);
+  }
+  return result;
+}
+function commitResetDispatchPrefix(state, chatId, cursorMessage) {
+  if (cursorMessage === void 0) return;
+  const cursor = cursorMessage.localId;
+  const pending = state.pendingMessageScans.get(chatId);
+  if (!pending?.readyForDispatch) {
+    state.lastSeenId.set(chatId, cursor);
+    return;
+  }
+  const exactIndex = pending.messages.findIndex(
+    (message) => cursorMessageKey(message) === cursorMessageKey(cursorMessage)
+  );
+  if (exactIndex < 0) {
+    throw new PendingRetryStateError(
+      `Successful reset cursor identity is absent from pending chat ${chatId}`,
+      "RETRY_STATE_CORRUPT"
+    );
+  }
+  const remaining = pending.messages.slice(exactIndex + 1);
+  const projected = new Map(state.pendingMessageScans);
+  if (remaining.length === 0) {
+    projected.delete(chatId);
+  } else {
+    projected.set(chatId, { ...pending, messages: remaining, retryCount: 0, nextRetryAt: 0 });
+  }
+  assertStateCapacity(projected);
+  state.lastSeenId.set(chatId, cursor);
+  state.pendingMessageScans.clear();
+  for (const [key, value] of projected) state.pendingMessageScans.set(key, value);
+  persist(state);
+}
+
 // src/access-control.ts
 import {
   buildChannelKeyCandidates,
@@ -5663,7 +6156,7 @@ function normalizeWeChatId(raw) {
   if (!trimmed) {
     return "";
   }
-  return trimmed.replace(/^wechat:/i, "").trim();
+  return trimmed.replace(/^(agent-wechat|wechat):/i, "").trim();
 }
 function normalizeWeChatAllowFrom(values) {
   const normalized = (values ?? []).map((entry) => String(entry).trim()).filter(Boolean).map((entry) => entry === "*" ? "*" : normalizeWeChatId(entry)).filter(Boolean);
@@ -5749,7 +6242,7 @@ function resolveWeChatPolicyContext(params) {
   const requireMention = firstDefined(groupEntry?.requireMention, wildcardEntry?.requireMention, true) !== false;
   const defaultGroupPolicy = resolveDefaultGroupPolicy(params.cfg);
   const { groupPolicy: fallbackGroupPolicy } = resolveAllowlistProviderRuntimeGroupPolicy({
-    providerConfigPresent: params.cfg.channels?.wechat !== void 0,
+    providerConfigPresent: params.cfg.channels?.["agent-wechat"] !== void 0 || params.cfg.channels?.wechat !== void 0,
     groupPolicy: normalizeGroupPolicy2(params.account.groupPolicy),
     defaultGroupPolicy: normalizeGroupPolicy2(defaultGroupPolicy)
   });
@@ -5864,6 +6357,310 @@ function nextReconnectState(input) {
   return { reconnect: true, dispatched: input.dispatched };
 }
 
+// src/inbound-media.ts
+import sharp from "sharp";
+var MIME_BY_FORMAT = {
+  jpeg: "image/jpeg",
+  jpg: "image/jpeg",
+  png: "image/png",
+  webp: "image/webp",
+  gif: "image/gif",
+  mp3: "audio/mpeg",
+  pdf: "application/pdf",
+  doc: "application/msword",
+  docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  xls: "application/vnd.ms-excel",
+  xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ppt: "application/vnd.ms-powerpoint",
+  pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  zip: "application/zip",
+  txt: "text/plain"
+};
+var MAX_IMAGE_BYTES = 20 * 1024 * 1024;
+var MAX_IMAGE_PIXELS = 4e7;
+var MAX_IMAGE_DIMENSION = 32768;
+var MAX_DECODED_IMAGE_BYTES = MAX_IMAGE_PIXELS * 4;
+var MAX_GIF_FRAMES = 64;
+var GIF_MAX_DICTIONARY_SIZE = 4096;
+var MAX_GIF_LZW_OPERATIONS = 1e7;
+var IMAGE_DECODE_TIMEOUT_SECONDS = 5;
+var SHARP_INPUT_OPTIONS = {
+  failOn: "warning",
+  limitInputPixels: MAX_IMAGE_PIXELS,
+  limitInputChannels: 5,
+  sequentialRead: true,
+  unlimited: false,
+  page: 0,
+  pages: 1,
+  animated: false
+};
+sharp.cache({ files: 0, items: 0, memory: 32 });
+sharp.concurrency(1);
+function imageMimeFromMagic(buf) {
+  if (buf.length >= 3 && buf[0] === 255 && buf[1] === 216 && buf[2] === 255) return "image/jpeg";
+  if (buf.length >= 8 && buf.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) return "image/png";
+  if (buf.length >= 12 && buf.toString("ascii", 0, 4) === "RIFF" && buf.toString("ascii", 8, 12) === "WEBP") return "image/webp";
+  if (buf.length >= 6 && (buf.toString("ascii", 0, 6) === "GIF87a" || buf.toString("ascii", 0, 6) === "GIF89a")) return "image/gif";
+  return void 0;
+}
+function validDimensions(width, height) {
+  return Number.isInteger(width) && Number.isInteger(height) && width > 0 && height > 0 && width <= MAX_IMAGE_DIMENSION && height <= MAX_IMAGE_DIMENSION && width * height <= MAX_IMAGE_PIXELS;
+}
+var SHARP_FORMAT_BY_MIME = {
+  "image/jpeg": "jpeg",
+  "image/png": "png",
+  "image/webp": "webp",
+  "image/gif": "gif"
+};
+function skipGifSubBlocks(buffer, startOffset) {
+  let offset = startOffset;
+  while (offset < buffer.length) {
+    const size = buffer[offset++];
+    if (size === 0) return offset;
+    if (offset + size > buffer.length) return void 0;
+    offset += size;
+  }
+  return void 0;
+}
+var GifCodeReader = class {
+  offset;
+  blockRemaining = 0;
+  datum = 0;
+  bits = 0;
+  ended = false;
+  buffer;
+  constructor(buffer, startOffset) {
+    this.buffer = buffer;
+    this.offset = startOffset;
+  }
+  nextByte() {
+    if (this.ended) return void 0;
+    if (this.blockRemaining === 0) {
+      if (this.offset >= this.buffer.length) return void 0;
+      this.blockRemaining = this.buffer[this.offset++];
+      if (this.blockRemaining === 0) {
+        this.ended = true;
+        return void 0;
+      }
+      if (this.offset + this.blockRemaining > this.buffer.length) return void 0;
+    }
+    this.blockRemaining -= 1;
+    return this.buffer[this.offset++];
+  }
+  read(codeSize) {
+    while (this.bits < codeSize) {
+      const byte = this.nextByte();
+      if (byte === void 0) return void 0;
+      this.datum |= byte << this.bits;
+      this.bits += 8;
+    }
+    const code = this.datum & (1 << codeSize) - 1;
+    this.datum >>>= codeSize;
+    this.bits -= codeSize;
+    return code;
+  }
+  finishSubBlocks() {
+    if (this.ended) return this.offset;
+    this.offset += this.blockRemaining;
+    this.blockRemaining = 0;
+    return skipGifSubBlocks(this.buffer, this.offset);
+  }
+};
+function decodeExactGifLzwPixels(buffer, startOffset, minCodeSize, pixelCount, colorCount, operationBudget) {
+  if (!Number.isInteger(minCodeSize) || minCodeSize < 2 || minCodeSize > 8) return void 0;
+  const clearCode = 1 << minCodeSize;
+  const endCode = clearCode + 1;
+  const prefix = new Uint16Array(GIF_MAX_DICTIONARY_SIZE);
+  const suffix = new Uint8Array(GIF_MAX_DICTIONARY_SIZE);
+  const stack = new Uint8Array(GIF_MAX_DICTIONARY_SIZE + 1);
+  for (let code = 0; code < clearCode; code += 1) suffix[code] = code;
+  const reader = new GifCodeReader(buffer, startOffset);
+  let codeSize = minCodeSize + 1;
+  let available = clearCode + 2;
+  let oldCode = -1;
+  let first = 0;
+  let produced = 0;
+  let sawInitialClear = false;
+  while (produced <= pixelCount && operationBudget.remaining > 0) {
+    operationBudget.remaining -= 1;
+    const next = reader.read(codeSize);
+    if (next === void 0) return void 0;
+    if (!sawInitialClear) {
+      if (next !== clearCode) return void 0;
+      sawInitialClear = true;
+      continue;
+    }
+    if (next === clearCode) {
+      codeSize = minCodeSize + 1;
+      available = clearCode + 2;
+      oldCode = -1;
+      continue;
+    }
+    if (next === endCode) {
+      return produced === pixelCount ? reader.finishSubBlocks() : void 0;
+    }
+    if (next > available || next >= GIF_MAX_DICTIONARY_SIZE) return void 0;
+    if (oldCode === -1) {
+      if (next >= clearCode || next >= colorCount) return void 0;
+      produced += 1;
+      oldCode = next;
+      first = next;
+      continue;
+    }
+    const inCode = next;
+    let code = next;
+    let top = 0;
+    if (code === available) {
+      stack[top++] = first;
+      code = oldCode;
+    } else if (code > available) {
+      return void 0;
+    }
+    let links = 0;
+    while (code >= clearCode + 2) {
+      operationBudget.remaining -= 1;
+      if (operationBudget.remaining < 0 || code >= available || top >= stack.length || links++ >= GIF_MAX_DICTIONARY_SIZE) return void 0;
+      const value = suffix[code];
+      if (value >= colorCount) return void 0;
+      stack[top++] = value;
+      code = prefix[code];
+    }
+    if (code >= clearCode || code >= colorCount || top >= stack.length) return void 0;
+    first = suffix[code];
+    stack[top++] = first;
+    produced += top;
+    if (produced > pixelCount) return void 0;
+    if (available < GIF_MAX_DICTIONARY_SIZE) {
+      prefix[available] = oldCode;
+      suffix[available] = first;
+      available += 1;
+      if (available === 1 << codeSize && codeSize < 12) codeSize += 1;
+    }
+    oldCode = inCode;
+  }
+  return void 0;
+}
+function validateGifLzwStreams(buffer) {
+  if (buffer.length < 14) return false;
+  const canvasWidth = buffer.readUInt16LE(6);
+  const canvasHeight = buffer.readUInt16LE(8);
+  if (!validDimensions(canvasWidth, canvasHeight)) return false;
+  const logicalPacked = buffer[10];
+  const globalColorCount = (logicalPacked & 128) !== 0 ? 1 << (logicalPacked & 7) + 1 : 0;
+  let offset = 13 + globalColorCount * 3;
+  if (offset > buffer.length) return false;
+  let frameCount = 0;
+  const operationBudget = { remaining: MAX_GIF_LZW_OPERATIONS };
+  while (offset < buffer.length) {
+    const marker = buffer[offset++];
+    if (marker === 59) return frameCount > 0 && offset === buffer.length;
+    if (marker === 33) {
+      if (offset >= buffer.length) return false;
+      offset += 1;
+      const nextOffset2 = skipGifSubBlocks(buffer, offset);
+      if (nextOffset2 === void 0) return false;
+      offset = nextOffset2;
+      continue;
+    }
+    if (marker !== 44 || offset + 9 > buffer.length) return false;
+    const left = buffer.readUInt16LE(offset);
+    const top = buffer.readUInt16LE(offset + 2);
+    const width = buffer.readUInt16LE(offset + 4);
+    const height = buffer.readUInt16LE(offset + 6);
+    const packed = buffer[offset + 8];
+    offset += 9;
+    if (!validDimensions(width, height)) return false;
+    if (left + width > canvasWidth || top + height > canvasHeight) return false;
+    frameCount += 1;
+    if (frameCount > MAX_GIF_FRAMES) return false;
+    const localColorCount = (packed & 128) !== 0 ? 1 << (packed & 7) + 1 : 0;
+    if (localColorCount > 0) {
+      offset += localColorCount * 3;
+      if (offset > buffer.length) return false;
+    }
+    const colorCount = localColorCount || globalColorCount;
+    if (colorCount === 0 || offset >= buffer.length) return false;
+    const minCodeSize = buffer[offset++];
+    const nextOffset = decodeExactGifLzwPixels(
+      buffer,
+      offset,
+      minCodeSize,
+      width * height,
+      colorCount,
+      operationBudget
+    );
+    if (nextOffset === void 0) return false;
+    offset = nextOffset;
+  }
+  return false;
+}
+async function validateDecodedImage(buffer, mime) {
+  if (buffer.length > MAX_IMAGE_BYTES) return "MEDIA_IMAGE_TOO_LARGE";
+  if (mime === "image/gif" && !validateGifLzwStreams(buffer)) return "MEDIA_IMAGE_INVALID";
+  try {
+    const metadata = await sharp(buffer, SHARP_INPUT_OPTIONS).timeout({ seconds: IMAGE_DECODE_TIMEOUT_SECONDS }).metadata();
+    const width = metadata.width;
+    const height = metadata.pageHeight ?? metadata.height;
+    if (metadata.format !== SHARP_FORMAT_BY_MIME[mime]) return "MEDIA_IMAGE_INVALID";
+    if (!validDimensions(width, height)) return "MEDIA_IMAGE_TOO_LARGE";
+    const decoded = await sharp(buffer, SHARP_INPUT_OPTIONS).timeout({ seconds: IMAGE_DECODE_TIMEOUT_SECONDS }).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    const decodedBytes = decoded.data.length;
+    if (!validDimensions(decoded.info.width, decoded.info.height)) return "MEDIA_IMAGE_TOO_LARGE";
+    if (decodedBytes !== decoded.info.width * decoded.info.height * decoded.info.channels) return "MEDIA_IMAGE_INVALID";
+    if (decodedBytes > MAX_DECODED_IMAGE_BYTES) return "MEDIA_IMAGE_TOO_LARGE";
+    return void 0;
+  } catch {
+    return "MEDIA_IMAGE_INVALID";
+  }
+}
+async function validateInboundMedia(result) {
+  if (!result.data) return { ok: false, code: "MEDIA_EMPTY_DATA" };
+  const normalized = result.data.replace(/\s/g, "");
+  if (!normalized || normalized.length % 4 !== 0 || !/^[A-Za-z0-9+/]+={0,2}$/.test(normalized)) {
+    return { ok: false, code: "MEDIA_INVALID_BASE64" };
+  }
+  const buffer = Buffer.from(normalized, "base64");
+  if (buffer.length === 0) return { ok: false, code: "MEDIA_EMPTY_DATA" };
+  const declared = MIME_BY_FORMAT[result.format.toLowerCase()] ?? `application/${result.format || "octet-stream"}`;
+  if (result.type === "image") {
+    const detected = imageMimeFromMagic(buffer);
+    if (!detected || detected !== declared) return { ok: false, code: "MEDIA_MAGIC_MISMATCH" };
+    const invalidCode = await validateDecodedImage(buffer, detected);
+    if (invalidCode) return { ok: false, code: invalidCode };
+  }
+  return { ok: true, value: { buffer, mime: declared } };
+}
+function safeBodyAfterKnownMediaFailure(baseType, content) {
+  return baseType === 3 ? "[Image unavailable]" : content;
+}
+async function saveValidatedInboundMedia(result, save) {
+  const validated = await validateInboundMedia(result);
+  if (!validated.ok) return validated;
+  try {
+    const saved = await save(validated.value.buffer, validated.value.mime, result.filename);
+    if (!saved?.path || typeof saved.path !== "string" || !saved.path.trim()) {
+      return { ok: false, code: "MEDIA_SAVE_FAILED" };
+    }
+    return { ok: true, path: saved.path, mime: validated.value.mime };
+  } catch {
+    return { ok: false, code: "MEDIA_SAVE_FAILED" };
+  }
+}
+
+// src/inbound-media-poll.ts
+async function pollMedia(client, chatId, localId, log, maxAttempts = 15, intervalMs = 1e3) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const result = await client.getMedia(chatId, localId);
+    if (result.type === "unsupported") return null;
+    if (result.data) return result;
+    if (attempt < maxAttempts) {
+      log?.info?.(`[wechat:media] pending attempt=${attempt}/${maxAttempts}`);
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+  }
+  return null;
+}
+
 // src/monitor.ts
 var MEDIA_TYPES = /* @__PURE__ */ new Set([3, 34, 43]);
 var HISTORY_CONTEXT_MARKER = "[Chat messages since your last reply - for context]";
@@ -5880,22 +6677,6 @@ function sleep(ms, signal) {
     });
   });
 }
-async function pollMedia(client, chatId, localId, log, maxAttempts = 15, intervalMs = 1e3) {
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    const result = await client.getMedia(chatId, localId);
-    if (result.type === "unsupported") {
-      return null;
-    }
-    if (result.data) {
-      return result;
-    }
-    if (attempt < maxAttempts) {
-      log?.info?.(`[media] Attempt ${attempt}/${maxAttempts} for ${chatId}:${localId} returned no data, retrying...`);
-      await new Promise((r) => setTimeout(r, intervalMs));
-    }
-  }
-  return null;
-}
 function enqueueWeChatSystemEvent(text, contextKey) {
   try {
     const core = getWeChatRuntime();
@@ -5910,6 +6691,23 @@ async function startWeChatMonitor(opts) {
   const { account, abortSignal, setStatus, log } = opts;
   const client = new WeChatClient({ baseUrl: account.serverUrl, token: account.token });
   const lastSeenId = /* @__PURE__ */ new Map();
+  const equalCursorUnreadHandled = /* @__PURE__ */ new Map();
+  const startupBaselines = /* @__PURE__ */ new Map();
+  const chatScanState = { initialScanComplete: false };
+  const pendingMessageScans = loadPendingResetRetries(account.accountId);
+  for (const [chatId, pending] of pendingMessageScans) {
+    const cursor = pending.messages.reduce(
+      (max, message) => Math.max(max, message.localId),
+      0
+    );
+    if (cursor > 0) lastSeenId.set(chatId, cursor);
+  }
+  const retryState = {
+    pendingMessageScans,
+    lastSeenId,
+    persist: () => persistPendingResetRetries(account.accountId, pendingMessageScans)
+  };
+  trimPendingResetRetries(retryState);
   const groupHistory = /* @__PURE__ */ new Map();
   const GROUP_HISTORY_LIMIT = 50;
   let lastAuthCheck = 0;
@@ -5978,8 +6776,15 @@ async function startWeChatMonitor(opts) {
         }
       }
       let chats;
+      let isInitialSnapshot = false;
       try {
-        chats = await client.listChats(50);
+        if (!chatScanState.initialScanComplete) {
+          chats = await listInitialMonitorChatSnapshot(client, chatScanState);
+          isInitialSnapshot = true;
+        } else {
+          const page = await listNextMonitorChatPage(client, chatScanState);
+          chats = page.chats;
+        }
       } catch (err) {
         log?.error?.(
           `[wechat:${account.accountId}] Failed to list chats: ${err}`
@@ -5987,9 +6792,28 @@ async function startWeChatMonitor(opts) {
         await sleep(account.pollIntervalMs, abortSignal);
         continue;
       }
+      if (isInitialSnapshot) {
+        for (const chat of chats) {
+          const chatId = chat.username ?? chat.id;
+          if (!startupBaselines.has(chatId)) {
+            const baseline = seedStartupBaselineFromChat(chat);
+            if (baseline) startupBaselines.set(chatId, baseline);
+          }
+        }
+      }
       const unreadChats = chats.filter(
         (c) => c.unreadCount > 0 && !isOfficialAccount(c.username ?? c.id)
       );
+      for (const chat of unreadChats) {
+        const chatId = chat.username ?? chat.id;
+        if (chatScanState.initialScanComplete && !lastSeenId.has(chatId) && !startupBaselines.has(chatId)) {
+          startupBaselines.set(chatId, { localId: 0 });
+        }
+      }
+      const chatsToProcess = monitorChatsToProcess(chats, retryState);
+      for (const chatId of chatsToProcess.keys()) {
+        if (isOfficialAccount(chatId)) chatsToProcess.delete(chatId);
+      }
       if (unreadChats.length > 0) {
         log?.info?.(
           `[wechat:${account.accountId}] ${unreadChats.length} chat(s) with unreads`
@@ -5997,13 +6821,17 @@ async function startWeChatMonitor(opts) {
       }
       let deferredThisTick = 0;
       let dispatchedThisTick = 0;
-      if (unreadChats.length > 0) {
-        for (const chat of unreadChats) {
+      if (chatsToProcess.size > 0) {
+        for (const chat of chatsToProcess.values()) {
           if (abortSignal.aborted) break;
           const result = await processUnreadChat(
             client,
             chat,
             lastSeenId,
+            equalCursorUnreadHandled,
+            startupBaselines,
+            pendingMessageScans,
+            retryState.persist,
             account,
             cfg,
             log,
@@ -6040,6 +6868,10 @@ async function startWeChatMonitor(opts) {
           client,
           chat,
           lastSeenId,
+          equalCursorUnreadHandled,
+          startupBaselines,
+          pendingMessageScans,
+          retryState.persist,
           account,
           cfg,
           log,
@@ -6115,44 +6947,28 @@ async function prepareMessage(client, msg, chatId, chat, liveAccount, policy, lo
       const result = await pollMedia(client, chatId, msg.localId, log);
       if (result && result.data && result.type !== "unsupported") {
         hasMedia = true;
-        log?.info?.(`[wechat:${liveAccount.accountId}] Media result: type=${result.type}, format=${result.format}, hasData=${!!result.data}, filename=${result.filename}`);
-        const mimeMap = {
-          jpeg: "image/jpeg",
-          jpg: "image/jpeg",
-          png: "image/png",
-          gif: "image/gif",
-          mp3: "audio/mpeg",
-          pdf: "application/pdf",
-          doc: "application/msword",
-          docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
-          xls: "application/vnd.ms-excel",
-          xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-          ppt: "application/vnd.ms-powerpoint",
-          pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
-          zip: "application/zip",
-          txt: "text/plain"
-        };
-        mediaMime = mimeMap[result.format] ?? `application/${result.format || "octet-stream"}`;
-        const buf = Buffer.from(result.data, "base64");
-        const saved = await core.channel.media.saveMediaBuffer(
-          buf,
-          mediaMime,
-          "inbound",
-          void 0,
-          result.filename
+        log?.info?.(`[wechat:media] inbound media received type=${result.type} format=${result.format}`);
+        const saved = await saveValidatedInboundMedia(
+          result,
+          async (buffer, mime, filename) => core.channel.media.saveMediaBuffer(buffer, mime, "inbound", void 0, filename)
         );
-        mediaPath = saved?.path;
-        log?.info?.(`[wechat:${liveAccount.accountId}] Saved media to ${mediaPath}`);
+        if (!saved.ok) {
+          log?.error?.(`[wechat:media] inbound media rejected code=${saved.code}`);
+        } else {
+          mediaMime = saved.mime;
+          mediaPath = saved.path;
+          log?.info?.("[wechat:media] inbound media saved");
+        }
       } else if (MEDIA_TYPES.has(baseType)) {
         hasMedia = true;
-        log?.info?.(`[wechat:${liveAccount.accountId}] Media not available after retries for msg ${msg.localId}`);
+        log?.info?.("[wechat:media] inbound media unavailable after retries");
       }
     } catch (err) {
-      log?.error?.(`[wechat:${liveAccount.accountId}] Media download failed: ${err}`);
+      log?.error?.("[wechat:media] inbound media failed code=MEDIA_DOWNLOAD_FAILED");
     }
   }
   const timestamp = new Date(msg.timestamp).getTime();
-  let rawBody = msg.content || "";
+  let rawBody = mediaPath ? msg.content || "" : safeBodyAfterKnownMediaFailure(baseType, msg.content || "");
   if (mediaPath && mediaMime) {
     if (!rawBody) {
       if (mediaMime.startsWith("audio/")) {
@@ -6220,7 +7036,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
   const mediaPath = mediaMsg?.mediaPath;
   const mediaMime = mediaMsg?.mediaMime;
   log?.info?.(
-    `[wechat:${liveAccount.accountId}] Dispatching segment: ${segment.length} msg(s), last=${msg.localId}${mediaPath ? ` media=${mediaPath}` : ""}`
+    `[wechat:${liveAccount.accountId}] Dispatching segment: ${segment.length} msg(s), last=${msg.localId}${mediaPath ? " media=present" : ""}`
   );
   const hasControlCommand = allowTextCommands && core.channel.commands.isControlCommandMessage(commandBody, cfg);
   const commandAuthorized = await resolveWeChatCommandAuthorization({
@@ -6260,7 +7076,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
   try {
     const route = core.channel.routing.resolveAgentRoute({
       cfg,
-      channel: "wechat",
+      channel: OPENCLAW_CHANNEL_ID,
       accountId: liveAccount.accountId,
       peer: {
         kind: isGroup ? "group" : "direct",
@@ -6332,21 +7148,21 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
       RawBody: rawBody,
       CommandBody: commandBody,
       InboundHistory: inboundHistory,
-      From: isGroup ? `wechat:group:${chatId}` : `wechat:${senderId}`,
-      To: `wechat:${chatId}`,
+      From: isGroup ? `${OPENCLAW_CHANNEL_ID}:group:${chatId}` : `${OPENCLAW_CHANNEL_ID}:${senderId}`,
+      To: `${OPENCLAW_CHANNEL_ID}:${chatId}`,
       SessionKey: route.sessionKey,
       AccountId: route.accountId,
       ChatType: isGroup ? "group" : "direct",
       ConversationLabel: fromLabel,
       SenderName: senderName || void 0,
       SenderId: senderId,
-      Provider: "wechat",
-      Surface: "wechat",
-      MessageSid: `wechat:${chatId}:${msg.localId}`,
+      Provider: OPENCLAW_CHANNEL_ID,
+      Surface: OPENCLAW_CHANNEL_ID,
+      MessageSid: `${OPENCLAW_CHANNEL_ID}:${chatId}:${msg.localId}`,
       WasMentioned: isGroup ? mentionGate.effectiveWasMentioned : void 0,
       CommandAuthorized: commandAuthorized,
-      OriginatingChannel: "wechat",
-      OriginatingTo: `wechat:${chatId}`,
+      OriginatingChannel: OPENCLAW_CHANNEL_ID,
+      OriginatingTo: `${OPENCLAW_CHANNEL_ID}:${chatId}`,
       ...mediaPath ? { MediaPath: mediaPath, MediaUrl: mediaPath, MediaType: mediaMime } : {},
       ...msg.reply ? {
         ReplyToBody: msg.reply.content.length > 50 ? msg.reply.content.slice(0, 50) + "..." : msg.reply.content,
@@ -6366,7 +7182,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
     const { onModelSelected, ...prefixOptions } = createChannelReplyPipeline({
       cfg,
       agentId: route.agentId,
-      channel: "wechat",
+      channel: OPENCLAW_CHANNEL_ID,
       accountId: liveAccount.accountId
     });
     await core.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
@@ -6378,7 +7194,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
           const mediaList = payload.mediaUrls?.length ? payload.mediaUrls : payload.mediaUrl ? [payload.mediaUrl] : [];
           const tableMode = core.channel.text.resolveMarkdownTableMode({
             cfg,
-            channel: "wechat",
+            channel: OPENCLAW_CHANNEL_ID,
             accountId: liveAccount.accountId
           });
           const text = core.channel.text.convertMarkdownTables(
@@ -6447,7 +7263,7 @@ async function dispatchSegment(segment, client, chatId, chat, liveAccount, polic
       }
     });
     core.channel.activity?.record?.({
-      channel: "wechat",
+      channel: OPENCLAW_CHANNEL_ID,
       accountId: liveAccount.accountId,
       direction: "inbound",
       at: timestamp
@@ -6473,11 +7289,11 @@ function bufferGroupHistory(groupHistory, chatId, pm, limit) {
     if (first) groupHistory.delete(first);
   }
 }
-async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, skipOpen, groupHistory, groupHistoryLimit, catchup) {
+async function processUnreadChat(client, chat, lastSeenId, equalCursorUnreadHandled, startupBaselines, pendingMessageScans, persistRetryState, account, cfg, log, skipOpen, groupHistory, groupHistoryLimit, catchup) {
   const core = getWeChatRuntime();
   const liveAccount = resolveWeChatAccount(cfg, account.accountId) ?? account;
   const chatId = chat.username ?? chat.id;
-  const storeAllowFrom = await core.channel.pairing.readAllowFromStore({ channel: "wechat", accountId: liveAccount.accountId, env: process.env }).catch(() => []);
+  const storeAllowFrom = await core.channel.pairing.readAllowFromStore({ channel: OPENCLAW_CHANNEL_ID, accountId: liveAccount.accountId, env: process.env }).catch(() => []);
   const policy = resolveWeChatPolicyContext({
     account: liveAccount,
     cfg,
@@ -6486,9 +7302,12 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
   });
   const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
     cfg,
-    surface: "wechat"
+    surface: OPENCLAW_CHANNEL_ID
   });
-  if (!skipOpen) {
+  let opened = false;
+  const openChatIfNeeded = async () => {
+    if (skipOpen || opened) return;
+    opened = true;
     log?.info?.(`[wechat:${liveAccount.accountId}] Opening chat ${chatId}...`);
     try {
       await client.openChat(chatId, true);
@@ -6498,14 +7317,54 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
         `[wechat:${liveAccount.accountId}] Failed to open chat ${chatId}: ${err}`
       );
     }
-  }
+  };
   const firstPoll = !lastSeenId.has(chatId);
   const prevLastSeen = lastSeenId.get(chatId) ?? 0;
-  const recoveryWindow = Math.max(liveAccount.catchUpMaxMessages, 20);
-  const fetchLimit = Math.min(Math.max(chat.unreadCount, 20), recoveryWindow);
+  const startupBaseline = startupBaselines.get(chatId);
   let messages;
+  let generationResetConfirmed = false;
   try {
-    messages = await client.listMessages(chatId, fetchLimit);
+    const pending = pendingMessageScans.get(chatId);
+    if (pending?.readyForDispatch) {
+      const pendingTail = pending.messages.at(-1)?.localId ?? 0;
+      const scan = await listMessagesForMonitorCursor(client, chatId, {
+        chat,
+        firstPoll: false,
+        prevLastSeen: pendingTail,
+        handledCursor: equalCursorUnreadHandled.get(chatId)
+      });
+      messages = mergePendingResetMessages(
+        { pendingMessageScans, lastSeenId, persist: persistRetryState },
+        chatId,
+        chat,
+        scan.messages
+      );
+      generationResetConfirmed = pending.generationReset === true;
+    } else {
+      const scan = await listMessagesForMonitorCursor(client, chatId, {
+        chat,
+        firstPoll,
+        prevLastSeen,
+        startupBaseline,
+        handledCursor: equalCursorUnreadHandled.get(chatId),
+        continuation: pending
+      });
+      if (!scan.complete) {
+        pendingMessageScans.set(chatId, {
+          chat,
+          cursor: scan.nextCursor,
+          messages: scan.messages,
+          generationReset: scan.generationReset
+        });
+        log?.info?.(
+          `[wechat:${liveAccount.accountId}] ${chatId}: deferred after ${scan.pagesScanned} message page(s); continuing paged scan next tick`
+        );
+        return "deferred";
+      }
+      messages = scan.messages;
+      generationResetConfirmed = scan.generationReset === true;
+      pendingMessageScans.delete(chatId);
+    }
   } catch (err) {
     log?.error?.(
       `[wechat:${liveAccount.accountId}] Failed to list messages for ${chatId}: ${err}`
@@ -6516,33 +7375,72 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
     `[wechat:${liveAccount.accountId}] ${chatId}: fetched ${messages.length} msgs, firstPoll=${firstPoll}, prevLastSeen=${prevLastSeen}, unreadCount=${chat.unreadCount}`
   );
   if (messages.length === 0) return "skipped";
-  let newMessages;
-  if (firstPoll) {
-    messages.sort((a, b) => a.localId - b.localId);
-    const unread = chat.unreadCount ?? 0;
-    if (unread > 0 && unread < messages.length) {
-      newMessages = messages.slice(-unread);
-      const seenMax = messages[messages.length - unread - 1].localId;
-      lastSeenId.set(chatId, seenMax);
-    } else if (unread >= messages.length) {
-      newMessages = messages;
-    } else {
-      const maxId2 = messages[messages.length - 1].localId;
-      lastSeenId.set(chatId, maxId2);
-      return "skipped";
+  const enrichedBaseline = enrichStartupBaselineFromMessages(startupBaseline, messages);
+  if (enrichedBaseline) {
+    startupBaselines.set(chatId, enrichedBaseline);
+  }
+  const selected = selectCursorMessages(
+    chatId,
+    chat,
+    messages,
+    lastSeenId,
+    equalCursorUnreadHandled,
+    enrichedBaseline,
+    generationResetConfirmed
+  );
+  let newMessages = selected.messages;
+  if (selected.generationReset && !pendingMessageScans.get(chatId)?.readyForDispatch) {
+    queueResetGenerationRetry(
+      { pendingMessageScans, lastSeenId, persist: persistRetryState },
+      chatId,
+      chat,
+      newMessages
+    );
+  }
+  const advanceLastSeen = (handledMessages) => {
+    const cursor = markCursorMessagesHandled(chatId, handledMessages, equalCursorUnreadHandled);
+    if (cursor !== void 0) {
+      lastSeenId.set(chatId, cursor);
+      if (selected.generationReset) {
+        startupBaselines.delete(chatId);
+      }
+      const baseline = startupBaselines.get(chatId);
+      if (baseline && cursor >= baseline.localId) {
+        startupBaselines.delete(chatId);
+      }
+      const exactCursorMessage = handledMessages.reduce(
+        (latest, message) => latest === void 0 || message.localId > latest.localId ? message : message.localId === latest.localId ? message : latest,
+        void 0
+      );
+      commitResetDispatchPrefix(
+        { pendingMessageScans, lastSeenId, persist: persistRetryState },
+        chatId,
+        exactCursorMessage
+      );
     }
-  } else {
-    newMessages = messages.filter((m) => m.localId > prevLastSeen);
-    if (newMessages.length === 0) {
-      return "skipped";
+  };
+  const seedLastSeen = selected.seedLastSeen;
+  if (seedLastSeen !== void 0) {
+    advanceLastSeen(messages.filter((message) => message.localId <= seedLastSeen));
+  }
+  if (newMessages.length === 0) {
+    if (selected.generationReset) {
+      clearPendingResetRetry(
+        { pendingMessageScans, lastSeenId, persist: persistRetryState },
+        chatId
+      );
     }
-    newMessages.sort((a, b) => a.localId - b.localId);
+    if (chat.unreadCount > 0) {
+      await openChatIfNeeded();
+    }
+    return "skipped";
   }
+  await openChatIfNeeded();
   const catchUpLimits = {
     maxMessages: liveAccount.catchUpMaxMessages,
     maxAgeMs: liveAccount.catchUpMaxAgeMs
   };
-  const isRecovery = firstPoll || skipOpen === true && isCatchUpBatch(newMessages, catchUpLimits);
+  const isRecovery = firstPoll && startupBaseline === void 0 || skipOpen === true && isCatchUpBatch(newMessages, catchUpLimits);
   if (isRecovery) {
     const selection = selectCatchUpMessages(
       newMessages,
@@ -6551,7 +7449,7 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
     );
     const observedCursor = recoveryCursor(selection);
     if (liveAccount.catchUpMode === "read-only") {
-      lastSeenId.set(chatId, observedCursor);
+      advanceLastSeen(messages.filter((message) => message.localId <= observedCursor));
       log?.info?.(
         `[wechat:${liveAccount.accountId}] Recovery read-only: advanced ${chatId} to ${observedCursor} without dispatching ${newMessages.length} msg(s)`
       );
@@ -6559,7 +7457,7 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
     }
     newMessages = selection.messages;
     if (newMessages.length === 0) {
-      lastSeenId.set(chatId, observedCursor);
+      advanceLastSeen(messages.filter((message) => message.localId <= observedCursor));
       log?.info?.(
         `[wechat:${liveAccount.accountId}] Recovery skipped ${selection.skipped} stale msg(s) in ${chatId}`
       );
@@ -6597,7 +7495,7 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
         }
         log?.info?.(`[wechat:${liveAccount.accountId}] Buffered ${processed.length} msg(s) for group history in ${chatId}`);
         const maxId2 = Math.max(...newMessages.map((m) => m.localId));
-        lastSeenId.set(chatId, maxId2);
+        advanceLastSeen(newMessages.filter((message) => message.localId <= maxId2));
         return "skipped";
       }
       if (hasMention) {
@@ -6654,7 +7552,7 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
     }
     if (decision.action === "defer") {
       log?.info?.(
-        `[wechat:${liveAccount.accountId}] Catch-up hold for ${chatId} (budget ${liveAccount.catchUpChatBudget}); raise channels.wechat.catchUpChatBudget to continue`
+        `[wechat:${liveAccount.accountId}] Catch-up hold for ${chatId} (budget ${liveAccount.catchUpChatBudget}); raise channels.${OPENCLAW_CHANNEL_ID}.catchUpChatBudget to continue`
       );
       return "deferred";
     }
@@ -6662,8 +7560,8 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
       log?.info?.(
         `[wechat:${liveAccount.accountId}] Skipping stale group chatter in ${chatId}`
       );
-      const maxId3 = Math.max(...newMessages.map((m) => m.localId));
-      lastSeenId.set(chatId, maxId3);
+      const maxId2 = Math.max(...newMessages.map((m) => m.localId));
+      advanceLastSeen(newMessages.filter((message) => message.localId <= maxId2));
       return "skipped";
     }
     const fold = shouldFoldSegments(catchup?.isReconnect ?? false) && !hasControlCommandInWindow;
@@ -6672,6 +7570,7 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
       `[wechat:${liveAccount.accountId}] ${chatId}: ${processed.length} dispatchable msg(s) in ${segments.length} segment(s) (${decision.reason})`
     );
     let allDispatched = true;
+    const successfulSegmentLastLocalIds = [];
     for (let i = 0; i < segments.length; i++) {
       const remaining = segments.length - i - 1;
       const dispatched = await dispatchSegment(
@@ -6689,17 +7588,27 @@ async function processUnreadChat(client, chat, lastSeenId, account, cfg, log, sk
       );
       if (!dispatched) {
         allDispatched = false;
+        break;
       }
+      successfulSegmentLastLocalIds.push(
+        Math.max(...segments[i].map((pm) => pm.msg.localId))
+      );
     }
     if (clearBufferedHistory && allDispatched && groupHistory) {
       groupHistory.set(chatId, []);
     }
-    const maxId2 = Math.max(...newMessages.map((m) => m.localId));
-    lastSeenId.set(chatId, maxId2);
+    const handledMessages = allDispatched ? newMessages : selectMessagesHandledAfterDispatch(newMessages, successfulSegmentLastLocalIds);
+    advanceLastSeen(handledMessages);
+    if (!allDispatched) {
+      recordResetRetryFailure(
+        { pendingMessageScans, lastSeenId, persist: persistRetryState },
+        chatId
+      );
+    }
     return allDispatched ? "dispatched" : "skipped";
   }
   const maxId = Math.max(...newMessages.map((m) => m.localId));
-  lastSeenId.set(chatId, maxId);
+  advanceLastSeen(newMessages.filter((message) => message.localId <= maxId));
   return "skipped";
 }
 
@@ -6709,7 +7618,7 @@ function collectWeChatStatusIssues(accounts) {
   for (const snapshot of accounts) {
     if (snapshot.connected === false) {
       issues.push({
-        channel: "wechat",
+        channel: "agent-wechat",
         accountId: snapshot.accountId,
         kind: "runtime",
         message: snapshot.lastError ? `Cannot reach agent-wechat server: ${snapshot.lastError}` : "Cannot reach agent-wechat server.",
@@ -6717,7 +7626,7 @@ function collectWeChatStatusIssues(accounts) {
       });
     } else if (snapshot.authStatus === "app_not_running") {
       issues.push({
-        channel: "wechat",
+        channel: "agent-wechat",
         accountId: snapshot.accountId,
         kind: "runtime",
         message: "WeChat application is not running. It should restart automatically.",
@@ -6725,11 +7634,11 @@ function collectWeChatStatusIssues(accounts) {
       });
     } else if (snapshot.linked === false) {
       issues.push({
-        channel: "wechat",
+        channel: "agent-wechat",
         accountId: snapshot.accountId,
         kind: "auth",
         message: "WeChat session not authenticated.",
-        fix: "Run: openclaw channels login --channel wechat"
+        fix: "Run: openclaw channels login --channel agent-wechat"
       });
     }
   }
@@ -7148,7 +8057,7 @@ async function sendWeChatText(cfg, to, text) {
     }
     throw new Error(result.error ?? "Send failed");
   }
-  return `wechat:${to}:${Date.now()}`;
+  return `${OPENCLAW_CHANNEL_ID}:${to}:${Date.now()}`;
 }
 async function sendWeChatMedia(cfg, to, text, mediaUrl) {
   const account = resolveWeChatAccount(cfg);
@@ -7161,7 +8070,7 @@ async function sendWeChatMedia(cfg, to, text, mediaUrl) {
       source: "openclaw"
     });
     if (!result.success) throw new Error(result.error ?? "Send failed");
-    return `wechat:${to}:${Date.now()}`;
+    return `${OPENCLAW_CHANNEL_ID}:${to}:${Date.now()}`;
   }
   const fsmod = await import("fs/promises");
   const pathmod = await import("path");
@@ -7198,10 +8107,10 @@ async function sendWeChatMedia(cfg, to, text, mediaUrl) {
     interPartDelayMs: account.mediaPartDelayMs,
     source: "openclaw"
   });
-  return `wechat:${to}:${requestId}`;
+  return `${OPENCLAW_CHANNEL_ID}:${to}:${requestId}`;
 }
 var wechatMessageAdapter = createChannelMessageAdapterFromOutbound({
-  id: "wechat",
+  id: OPENCLAW_CHANNEL_ID,
   capabilities: {
     text: true,
     media: true,
@@ -7209,26 +8118,26 @@ var wechatMessageAdapter = createChannelMessageAdapterFromOutbound({
   },
   outbound: {
     sendText: async ({ cfg, to, text }) => ({
-      channel: "wechat",
+      channel: OPENCLAW_CHANNEL_ID,
       messageId: await sendWeChatText(cfg, to, text)
     }),
     sendMedia: async ({ cfg, to, text, mediaUrl }) => ({
-      channel: "wechat",
+      channel: OPENCLAW_CHANNEL_ID,
       messageId: await sendWeChatMedia(cfg, to, text, mediaUrl)
     })
   }
 });
 var meta = {
-  id: "wechat",
+  id: OPENCLAW_CHANNEL_ID,
   label: "WeChat",
-  selectionLabel: "WeChat (\u5FAE\u4FE1)",
+  selectionLabel: "WeChat (agent-wechat)",
   blurb: "WeChat messaging via agent-wechat container.",
   docsPath: "wechat",
-  aliases: ["weixin"],
+  aliases: [],
   order: 80
 };
 var wechatPlugin = {
-  id: "wechat",
+  id: OPENCLAW_CHANNEL_ID,
   meta,
   gatewayMethods: ["web.login.start", "web.login.wait"],
   capabilities: {
@@ -7238,7 +8147,7 @@ var wechatPlugin = {
     media: true,
     reply: true
   },
-  reload: { configPrefixes: ["channels.wechat"] },
+  reload: { configPrefixes: [`channels.${OPENCLAW_CHANNEL_ID}`, "channels.wechat"] },
   configSchema: {
     schema: {
       type: "object",
@@ -7314,23 +8223,23 @@ var wechatPlugin = {
     },
     isEnabled: (account) => account.enabled && !!account.serverUrl,
     isConfigured: (account) => !!account.serverUrl,
-    unconfiguredReason: () => "No serverUrl configured. Run: openclaw channels setup wechat"
+    unconfiguredReason: () => "No serverUrl configured. Run: openclaw channels setup agent-wechat"
   },
   // ---- Security adapter ----
   security: {
     resolveDmPolicy: ({ account }) => ({
       policy: account.dmPolicy ?? "disabled",
       allowFrom: account.allowFrom ?? [],
-      allowFromPath: "channels.wechat.allowFrom",
-      policyPath: "channels.wechat.dmPolicy",
-      approveHint: "Add the wxid to channels.wechat.allowFrom",
-      normalizeEntry: (raw) => raw.replace(/^wechat:/i, "").trim()
+      allowFromPath: `channels.${OPENCLAW_CHANNEL_ID}.allowFrom`,
+      policyPath: `channels.${OPENCLAW_CHANNEL_ID}.dmPolicy`,
+      approveHint: `Add the wxid to channels.${OPENCLAW_CHANNEL_ID}.allowFrom`,
+      normalizeEntry: (raw) => raw.replace(/^(agent-wechat|wechat):/i, "").trim()
     })
   },
   // ---- Groups adapter ----
   groups: {
     resolveRequireMention: ({ cfg, groupId }) => {
-      const wechat = cfg?.channels?.wechat;
+      const wechat = cfg?.channels?.[OPENCLAW_CHANNEL_ID] ?? cfg?.channels?.wechat;
       if (!wechat) return true;
       if (!groupId) {
         return wechat.groups?.["*"]?.requireMention ?? true;
@@ -7355,10 +8264,10 @@ var wechatPlugin = {
   },
   // ---- Messaging adapter ----
   messaging: {
-    normalizeTarget: (raw) => raw.replace(/^wechat:/i, "").trim() || void 0,
+    normalizeTarget: (raw) => raw.replace(/^(agent-wechat|wechat):/i, "").trim() || void 0,
     targetResolver: {
       looksLikeId: (raw) => {
-        const stripped = raw.replace(/^wechat:/i, "").trim();
+        const stripped = raw.replace(/^(agent-wechat|wechat):/i, "").trim();
         return stripped.includes("@chatroom") || stripped.startsWith("wxid_");
       },
       hint: "WeChat ID (wxid_xxx or xxx@chatroom)"
@@ -7368,11 +8277,11 @@ var wechatPlugin = {
   outbound: {
     deliveryMode: "direct",
     sendText: async ({ cfg, to, text }) => ({
-      channel: "wechat",
+      channel: OPENCLAW_CHANNEL_ID,
       messageId: await sendWeChatText(cfg, to, text)
     }),
     sendMedia: async ({ cfg, to, text, mediaUrl }) => ({
-      channel: "wechat",
+      channel: OPENCLAW_CHANNEL_ID,
       messageId: await sendWeChatMedia(cfg, to, text, mediaUrl)
     })
   },
@@ -7399,7 +8308,7 @@ var wechatPlugin = {
         accountId ?? void 0
       );
       if (!account?.serverUrl) {
-        return { message: "No serverUrl configured. Run: openclaw channels setup wechat" };
+        return { message: "No serverUrl configured. Run: openclaw channels setup agent-wechat" };
       }
       const client = new WeChatClient({ baseUrl: account.serverUrl, token: account.token });
       try {
@@ -7440,7 +8349,7 @@ var wechatPlugin = {
       );
       if (!account?.serverUrl) {
         throw new Error(
-          "No serverUrl configured. Run: openclaw channels setup wechat"
+          "No serverUrl configured. Run: openclaw channels setup agent-wechat"
         );
       }
       const client = new WeChatClient({ baseUrl: account.serverUrl, token: account.token });
@@ -7600,8 +8509,8 @@ Error: ${event.message}`);
         ...cfg,
         channels: {
           ...cfg.channels,
-          wechat: {
-            ...cfg.channels?.wechat,
+          [OPENCLAW_CHANNEL_ID]: {
+            ...cfg.channels?.[OPENCLAW_CHANNEL_ID] ?? cfg.channels?.wechat,
             enabled: true,
             serverUrl,
             ...token ? { token } : {}
@@ -7614,7 +8523,7 @@ Error: ${event.message}`);
 
 // index.ts
 var plugin = {
-  id: "wechat",
+  id: OPENCLAW_CHANNEL_ID,
   name: "WeChat",
   description: "WeChat channel via agent-wechat container",
   configSchema: emptyPluginConfigSchema(),