@clawling/clawchat-plugin-openclaw 2026.6.16-4 → 2026.6.22-1

package/src/runtime.ts

@@ -27,6 +27,7 @@ import {
   CHANNEL_ID,
   effectiveOutputVisibility,
   effectiveGroupCommandMode,
+  effectiveGroupMode,
   hasOpenclawClawlingConnectCredentials,
   resolveOpenclawClawlingAccount,
   type ResolvedOpenclawClawlingAccount,
@@ -48,6 +49,7 @@ import {
   clawChatDbPathForStateDir,
   getClawChatStore,
   type ClawChatStore,
+  type MessageRow,
 } from "./storage.ts";
 import { getClawChatGroupPrompt, getClawChatUserPrompt } from "./plugin-prompts.ts";
 import {
@@ -66,6 +68,7 @@ import {
 } from "./prompt-injection.ts";
 import { createGroupMessageCoalescer } from "./group-message-coalescer.ts";
 import { openclawLlmContextDebug } from "./llm-context-debug.ts";
+import { GroupSettingsCache } from "./group-settings.ts";
 
 type Log = { debug?: (m: string) => void; info?: (m: string) => void; error?: (m: string) => void };
 type ChannelContextBuilder = (params: Record<string, unknown>) => unknown;
@@ -96,6 +99,7 @@ type RuntimeConnectionStore = Pick<
       | "markActivationBootstrapSent"
       | "getActivationConversation"
       | "getLastResolvedDeviceId"
+      | "listRecentGroupMessages"
     >
   >;
 
@@ -107,6 +111,14 @@ export { setOpenclawClawlingRuntime, getOpenclawClawlingRuntime };
 const activeClients = new Map<string, ClawlingChatClient>();
 const CLAWCHAT_PLUGIN_SLASH_COMMANDS = new Set(["clawchat-activate", "clawchat-output"]);
 const ACTIVATION_CREDENTIAL_POLL_INTERVAL_MS = 2_000;
+// Upper bound (ms) on how long group ingest waits for the FIRST group-settings
+// pull to settle before proceeding anyway. Best-effort governance must never
+// permanently disable group traffic, so a stalled initial GET (endpoint accepts
+// but never responds) can hold the gate at most this long. Matches the sibling
+// 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([
@@ -641,6 +653,152 @@ export async function maybeAutoActivateFromEnv(
   return next;
 }
 
+// Re-armable "settings pull pending" gate — the openclaw analogue of the hermes
+// adapter's `asyncio.Event` (`_group_settings_ready`). It holds a single "ready"
+// promise that group dispatch awaits (bounded by GROUP_SETTINGS_READY_TIMEOUT_MS
+// at the call site). `arm()` re-closes the gate when a NEW settings pull starts
+// (startup, every reconnect after hello-ok, and on `agent.config.changed`) so a
+// later pull's in-flight cache write is never raced by a held group turn reading
+// the stale cache.
+//
+// Open condition (Finding 2 fix). The gate must NOT open just because the LATEST
+// pull settled: a newer pull can FAIL or return a non-authoritative result and
+// settle FIRST, while an earlier pull is still in flight and about to apply an
+// authoritative (e.g. just-muted) snapshot. Opening on the newer pull's settle
+// would let a held group turn proceed against the stale cache. So the gate opens
+// only when EITHER:
+//   (a) any in-flight pull APPLIED an authoritative snapshot (the cache is now
+//       fresh for this arm epoch — no need to wait for slower pulls), OR
+//   (b) there are no longer any in-flight pulls (every pull settled
+//       non-authoritatively / failed — nothing better is coming).
+// The bounded timeout/abort at the call site remains the ultimate backstop. The
+// gate is created already-OPEN so direct traffic and pre-pull harness paths are
+// never blocked; group dispatch only ever waits while a pull is actually pending.
+// Opaque token handed back by `arm()` and round-tripped to `release()`. Carries
+// both the pull's generation (latest-pull tracking) and its epoch (the re-close
+// counter used to retire stale older-epoch pulls). Callers treat it as opaque.
+interface SettingsReadyToken {
+  generation: number;
+  epoch: number;
+}
+
+interface SettingsReadyGate {
+  /** Re-close the gate for a starting pull; returns that pull's opaque token. */
+  arm(): SettingsReadyToken;
+  /**
+   * Mark a pull as settled. `authoritative` is true when the pull applied an
+   * authoritative snapshot (HTTP 200). A token from a SUPERSEDED epoch (the gate
+   * re-closed for a newer pull since this one was armed) is ignored entirely — it
+   * neither decrements the current epoch's in-flight count nor opens the gate.
+   * Otherwise the gate opens when an authoritative pull has landed for the current
+   * arm epoch, or when no in-flight pulls remain for that epoch.
+   */
+  release(token: SettingsReadyToken, authoritative: boolean): void;
+  /** Force the gate open regardless of in-flight pulls (abort/shutdown backstop). */
+  forceOpen(): void;
+  /** The current ready promise — resolved while open, pending while a pull runs. */
+  wait(): Promise<void>;
+}
+
+export function createSettingsReadyGate(): SettingsReadyGate {
+  let generation = 0;
+  // Epoch counter: incremented every time the gate RE-CLOSES (an arm() while the
+  // gate was open). `pending` is epoch-scoped — a pull armed in a prior epoch is
+  // retired and can neither keep nor reopen the current epoch's gate.
+  let epoch = 0;
+  // Number of CURRENT-epoch dispatched pulls that have not yet settled (released).
+  let pending = 0;
+  // Has an authoritative snapshot been applied since the gate last closed? Reset
+  // whenever the gate re-closes (the first arm() after an open).
+  let authoritativeApplied = false;
+  // Starts OPEN: a resolved promise so nothing blocks until the first arm().
+  let ready: Promise<void> = Promise.resolve();
+  let resolveReady: (() => void) | null = null;
+  const open = () => {
+    const resolve = resolveReady;
+    resolveReady = null;
+    resolve?.();
+  };
+  return {
+    arm(): SettingsReadyToken {
+      generation += 1;
+      // Only create a fresh pending promise when the gate is currently open; if a
+      // pull is already in flight (resolveReady set) keep the SAME promise so its
+      // existing waiters stay parked. When re-closing an open gate, start a NEW
+      // epoch: discard any stale pending count left over from pulls of the prior
+      // (now-closed) period — a startup pull that STALLED and never settled must
+      // not keep the new epoch's `pending` above zero forever — and clear the
+      // authoritative flag so the new epoch must observe a fresh authoritative
+      // pull (or drain to zero in-flight) before opening again.
+      if (resolveReady === null) {
+        epoch += 1;
+        pending = 0;
+        authoritativeApplied = false;
+        ready = new Promise<void>((resolve) => {
+          resolveReady = resolve;
+        });
+      }
+      pending += 1;
+      return { generation, epoch };
+    },
+    release(token: SettingsReadyToken, authoritative: boolean): void {
+      // Retire stale older-epoch pulls. The gate re-closed (a newer pull started)
+      // since this token was armed, so this release belongs to a superseded
+      // period. Ignore it entirely: a stalled startup pull settling LATE must
+      // neither decrement the current epoch's `pending` (which would spuriously
+      // open via pending===0) nor mark the current epoch authoritative.
+      if (token.epoch !== epoch) return;
+      // Count this current-epoch pull out of the in-flight set.
+      if (pending > 0) pending -= 1;
+      // Only the LATEST armed pull's authoritative snapshot may open the gate.
+      // An OLDER pull (e.g. an on-ready/reconnect pull armed before a config
+      // change) can return an authoritative HTTP-200 snapshot while a NEWER
+      // `agent.config.changed` pull — carrying the just-muted / mention-only
+      // state — is still in flight. Opening on that stale authoritative release
+      // would let held group traffic proceed against settings the newer pull is
+      // about to replace (Finding #3). So only set `authoritativeApplied` when
+      // this release is for the latest armed generation. An older-generation
+      // authoritative release merely decrements `pending`.
+      if (authoritative && token.generation === generation) authoritativeApplied = true;
+      // Open iff the cache is now authoritative for the LATEST epoch, OR no pull
+      // is still in flight (a slower, earlier pull could still be applying an
+      // authoritative snapshot, so a non-authoritative settle must NOT open the
+      // gate while `pending > 0`). The `pending === 0` backstop still fires when
+      // every pull has settled — including the older-authoritative-then-newer-
+      // failure case, where the older snapshot is the freshest available.
+      if (authoritativeApplied || pending === 0) open();
+    },
+    forceOpen(): void {
+      pending = 0;
+      open();
+    },
+    wait(): Promise<void> {
+      return ready;
+    },
+  };
+}
+
+// Resolve when `gate` settles, OR after `ms`, OR on abort — whichever comes
+// first. The timer is always cleared so it can't leak under fake timers. Used to
+// bound the first-group-settings-pull gate so a stalled pull can never hang group
+// traffic permanently (best-effort governance must always release).
+function waitWithTimeout(gate: Promise<void>, ms: number, abortSignal: AbortSignal): Promise<void> {
+  if (abortSignal.aborted) return Promise.resolve();
+  return new Promise<void>((resolve) => {
+    let settled = false;
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      abortSignal.removeEventListener("abort", finish);
+      resolve();
+    };
+    const timer = setTimeout(finish, Math.max(1, ms));
+    abortSignal.addEventListener("abort", finish, { once: true });
+    void gate.then(finish, finish);
+  });
+}
+
 function waitForActivationPoll(abortSignal: AbortSignal, ms: number): Promise<boolean> {
   if (abortSignal.aborted) return Promise.resolve(false);
   return new Promise((resolve) => {
@@ -1542,6 +1700,84 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     log: (msg) => log?.info?.(msg),
     context: wsLogContext,
   });
+  const groupSettingsCache = new GroupSettingsCache();
+  // Findings 2 & 3 — gate group dispatch on the IN-FLIGHT settings pull, not just
+  // the first one. The pull is fire-and-forget, so replayed/live group messages
+  // could otherwise enter the governance gate against a stale/empty cache
+  // (treating a just-muted/mention-only chat as default "all"). A RE-ARMABLE gate
+  // (`settingsReadyGate`) re-closes whenever a new pull starts — at startup, on
+  // every WS reconnect (after hello-ok), and on `agent.config.changed` — so a
+  // reconnect/config-change pull holds group traffic until the fresh settings
+  // land, mirroring the hermes adapter's `_group_settings_ready` event. Group
+  // ingest awaits it through a bounded race (`waitWithTimeout`,
+  // GROUP_SETTINGS_READY_TIMEOUT_MS) so even a stalled pull — endpoint accepts but
+  // never responds — can hold group traffic at most that long before the gate
+  // releases. Non-group traffic never awaits this.
+  const settingsReadyGate = createSettingsReadyGate();
+  // Best-effort re-pull of per-group agent settings from the backend.
+  // Called at startup, on every successful WS (re)connect, and on
+  // `notify.signal` with type "agent.config.changed".
+  //
+  // Finding 4 — `bypassRefresh` is set for the PRE-connect startup pull only. The
+  // normal pull runs through the REST `withRefresh` wrapper; a 401/403 there
+  // rotates `account.token`. But the WS client captured the token at construction
+  // (`createOpenclawClawlingClient`, `token: account.token`), so a pre-connect
+  // rotation would leave the client connecting with a stale token. The startup
+  // pull therefore calls the api-client WITHOUT the refresh wrapper: on auth
+  // failure it simply fails (empty cache + gate released), leaving the WS
+  // handshake — which has its own auth/refresh path — to own token rotation. The
+  // on-ready pull (post hello-ok) keeps the refresh wrapper.
+  // Monotonic fetch sequence: incremented once per dispatched pull and passed
+  // into `applyFetched` so the cache can order results across overlapping
+  // requests (including empty pulls, which have no row version to compare). A
+  // late result with a lower sequence is ignored, so a stale snapshot — empty
+  // or not — can never roll back newer state.
+  let groupSettingsFetchSequence = 0;
+  const pullGroupSettings = (opts?: { bypassRefresh?: boolean }): void => {
+    const sequence = ++groupSettingsFetchSequence;
+    // Re-close the gate SYNCHRONOUSLY, before the async pull is scheduled, so any
+    // group frame the read loop dispatches concurrently observes the closed gate
+    // (rather than slipping past against the pre-pull cache). The opaque token
+    // scopes the release by generation AND epoch, so a superseded pull (from a
+    // prior re-closed epoch) never re-opens or counts against a newer pull's gate.
+    const gateToken = settingsReadyGate.arm();
+    void (async () => {
+      // Whether THIS pull applied an authoritative (HTTP 200) snapshot. Only an
+      // authoritative apply opens the gate immediately; a non-authoritative /
+      // failed pull must not open the gate while an earlier pull is still in
+      // flight (Finding 2) — it only counts down the in-flight set.
+      let authoritative = false;
+      try {
+        const result = opts?.bypassRefresh
+          ? await (conversationApiClient ??= buildConversationApiClient()).getMyGroupSettings()
+          : await getConversationApiClient().getMyGroupSettings();
+        if (!result.authoritative) {
+          // Non-authoritative outcome (404 / endpoint-absent / malformed body):
+          // preserve the cache. This is NOT "cleared".
+          log?.info?.(
+            `[${accountId}] clawchat-plugin-openclaw group-settings pull non-authoritative seq=${sequence} (cache preserved)`,
+          );
+          return;
+        }
+        groupSettingsCache.applyFetched(result.rows, sequence);
+        authoritative = true;
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw group-settings pull ok seq=${sequence} rows=${result.rows.length}`,
+        );
+      } catch (err) {
+        log?.error?.(
+          `[${accountId}] clawchat-plugin-openclaw group-settings pull failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      } finally {
+        // Pull settled. Open the gate iff this pull applied an authoritative
+        // snapshot OR no in-flight pull remains. A non-authoritative/failed pull
+        // settling ahead of an earlier still-pending authoritative pull does NOT
+        // open the gate — the earlier pull's authoritative apply (or the call-site
+        // timeout/abort backstop) does.
+        settingsReadyGate.release(gateToken, authoritative);
+      }
+    })();
+  };
   const logAuthFailure = (reason: string) => {
     if (authFailureLogged) return;
     authFailureLogged = true;
@@ -1637,6 +1873,9 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       }
       void refreshConversationCacheAfterReady();
       void dispatchActivationBootstrap();
+      // Re-pull per-group agent settings on every successful (re)connect so the
+      // cache stays current after a network interruption or token refresh.
+      pullGroupSettings();
       // §A.1 — arm the proactive refresh timer from the live token's `exp`
       // every time a connection becomes ready (re-armed after every refresh via
       // the gateway re-enter).
@@ -1794,7 +2033,19 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     // cache (friends are fetched on demand via REST tools), so there is nothing
     // to invalidate — observe + dedup only. The live frame and its reliable
     // inbox replay carry the same event_id and collapse to one observation.
-    notifySignalObserver.observe(env);
+    const outcome = notifySignalObserver.observe(env);
+    if (outcome === "observed") {
+      const payload = env.payload && typeof env.payload === "object"
+        ? (env.payload as Record<string, unknown>)
+        : undefined;
+      const type = typeof payload?.type === "string" ? payload.type : "";
+      if (type === "agent.config.changed") {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw agent.config.changed signal received; re-pulling group settings`,
+        );
+        pullGroupSettings();
+      }
+    }
   });
 
   client.on("replay:done", (env: Envelope) => {
@@ -1865,7 +2116,7 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     }
   });
 
-  type IngestTurnResult = "submitted" | "skipped" | "failed";
+  type IngestTurnResult = "submitted" | "skipped" | "failed" | "stored_muted" | "stored_skipped";
   type GroupIngestTurnParams = IngestTurnParams & { peer: { kind: "group"; id: string } };
 
   const loadGroupParticipantsForPrompt = async (params: {
@@ -2243,10 +2494,95 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     }
   };
 
+  // Resolve the live mute / reply-mode / batch-window for a group chat from the
+  // backend settings cache, falling back to the static channel config. Shared by
+  // the enqueue-time gate (ingestTurn) and the flush-time re-gate (coalescer
+  // dispatch) so both decisions read the SAME source of truth.
+  const resolveGroupEffectiveSettings = (chatId: string) =>
+    groupSettingsCache.effective(chatId, {
+      muted: false,
+      replyMode: effectiveGroupMode(account, chatId),
+      batchDelaySeconds: 10,
+    });
+
   const groupCoalescer = createGroupMessageCoalescer<GroupIngestTurnParams>({
     idleMs: 10_000,
     maxWaitMs: 30_000,
     dispatch: async (turn) => {
+      // Finding 3 — gate the FLUSH path too. A queued non-mention batch can flush
+      // (idle/max timer) while an `agent.config.changed` settings pull is in
+      // flight; resolving effective settings here without awaiting the gate reads
+      // the stale cache and dispatches one reply for a chat about to be muted /
+      // flipped to mention-only. Await the same re-armable gate (bounded by
+      // GROUP_SETTINGS_READY_TIMEOUT_MS) so the flush-time re-check below sees the
+      // fresh snapshot.
+      //
+      // Finding #4 — do NOT early-return on abort here. The ingest path DOES early-
+      // return on abort, but only AFTER it has already taken the idempotency claim
+      // (`claimInboundTurn` runs BEFORE the gate wait there, so the frame is durably
+      // persisted before the interruptible wait — required by legacy advance-on-
+      // write delivery, where a frame written before a disconnect is not re-delivered
+      // on reconnect; see docs/client-integration.md §11.7). So even an ingest-time
+      // abort keeps the frame; it just skips dispatch. Here at FLUSH the batch was
+      // likewise already claimed at ingest AND `flush()` has already removed it from
+      // the coalescer's pending set. An abort early-return would therefore silently
+      // DROP an already-claimed, already-dequeued batch — and a replay of the same
+      // message_id is deduped by `claimMessageOnce`, permanently losing the group
+      // reply. The gate wait still runs and resolves immediately on abort (forceOpen)
+      // so we re-resolve against the freshest available settings, then dispatch
+      // best-effort rather than dropping.
+      await waitWithTimeout(settingsReadyGate.wait(), GROUP_SETTINGS_READY_TIMEOUT_MS, abortSignal);
+      // Finding 1 — re-evaluate governance at FLUSH time. Settings can change
+      // (via an agent.config.changed pull) while a coalesced batch sits pending,
+      // so the enqueue-time decision may be stale. Drop the batch if the chat is
+      // now muted, or if it flipped to mention-only and this batch carries no
+      // mention.
+      const eff = resolveGroupEffectiveSettings(turn.peer.id);
+      if (eff.muted) {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw coalesced group batch dropped at flush (now muted) chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        );
+        return;
+      }
+      if (eff.replyMode === "mention" && !turn.wasMentioned) {
+        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;
+      }
+      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;
+        }
+      }
       await dispatchTurnToAgent(turn);
     },
     onError: (err) => {
@@ -2298,9 +2634,49 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
       senderNickName: resolveSenderNickNameForTurn(rawTurn),
       ...senderBatchIdentity,
     };
-    const claimed = claimInboundTurn(turn);
-    if (claimed === "skipped") return "skipped";
     if (turn.peer.kind === "group") {
+      // Finding 1 corrected (message loss) — claim the inbound idempotency row
+      // BEFORE the (interruptible) settings-gate wait, so every received group
+      // frame is durably persisted EXACTLY ONCE before any wait that a shutdown
+      // can interrupt. This client does NOT advertise `reliable_delivery`
+      // (src/ws-client.ts), so under legacy delivery the server's replay cursor
+      // advances on socket-WRITE (docs/client-integration.md §11.7): a frame
+      // already written before a disconnect is NOT re-delivered on reconnect.
+      // `claimMessageOnce` is the ONLY durability an inbound has, and the store
+      // never reprocesses undispatched inbounds. So if we claimed only AFTER the
+      // wait, a shutdown-mid-wait would leave the frame neither persisted NOR
+      // replayed — permanently lost. Claiming first makes it durable; the abort
+      // check below then returns without dispatching, but the frame is kept.
+      // `claimInboundTurn` is INSERT OR IGNORE, so a genuine duplicate (same
+      // message_id) is still deduped here exactly once.
+      const claimed = claimInboundTurn(turn);
+      if (claimed === "skipped") return "skipped";
+      // Findings 2 & 3 — hold ALL group traffic until the in-flight settings pull
+      // has settled so the mute / reply-mode gate never runs against a stale/empty
+      // cache (startup, reconnect, AND config-change pulls all re-close the gate).
+      // This only delays group traffic; direct messages return below. The wait is
+      // bounded (GROUP_SETTINGS_READY_TIMEOUT_MS): a stalled pull must never hang
+      // group traffic forever, so the gate always releases — falling back to the
+      // (possibly stale) cache rather than blocking indefinitely.
+      await waitWithTimeout(settingsReadyGate.wait(), GROUP_SETTINGS_READY_TIMEOUT_MS, abortSignal);
+      // Finding (#2 follow-up) — the bounded wait also resolves on abort. If the
+      // gateway is closing, stop here instead of enqueuing/dispatching a group turn
+      // into a tearing-down gateway. The frame is already claimed (persisted), so
+      // returning here drops only the dispatch, never the message.
+      if (abortSignal.aborted) return "skipped";
+      // Mute gate — evaluated BEFORE the slash-command branch so a backend-muted
+      // group is fully store-only, consistent with muted normal messages: a
+      // muted group must never forward/dispatch a `/clawchat-*` command (or any
+      // group slash command) to the agent or the owner. Known commands were
+      // previously handled above this gate, which let a muted group still drive
+      // the agent — contradicting the mute semantics. Keep this check first.
+      const eff = resolveGroupEffectiveSettings(turn.peer.id);
+      if (eff.muted) {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw group message stored but muted chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        );
+        return "stored_muted";
+      }
       if (isKnownOpenClawGroupSlashCommand(turn.rawBody, cfg)) {
         if (isOpenClawConfirmSlashCommand(turn.rawBody)) {
           return forwardGroupApprovalSlashToOwner(turn);
@@ -2319,20 +2695,33 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
         );
         return dispatchTurnToAgent(turn);
       }
+      if (eff.replyMode === "mention" && !turn.wasMentioned) {
+        log?.info?.(
+          `[${accountId}] clawchat-plugin-openclaw group message stored but skipped (mention mode) chat_id=${turn.peer.id} msg=${turn.messageId}`,
+        );
+        return "stored_skipped";
+      }
+      const idleMsOverride = eff.batchDelaySeconds * 1000;
       if (turn.wasMentioned) {
-        groupCoalescer.enqueue(turn as GroupIngestTurnParams);
+        groupCoalescer.enqueue(turn as GroupIngestTurnParams, { idleMsOverride });
         groupCoalescer.flushNow(turn.peer.id);
         log?.info?.(
           `[${accountId}] clawchat-plugin-openclaw dispatching mentioned group batch chat_id=${turn.peer.id} msg=${turn.messageId}`,
         );
         return "submitted";
       }
-      groupCoalescer.enqueue(turn as GroupIngestTurnParams);
+      groupCoalescer.enqueue(turn as GroupIngestTurnParams, { idleMsOverride });
       log?.info?.(
         `[${accountId}] clawchat-plugin-openclaw queued group batch chat_id=${turn.peer.id} msg=${turn.messageId}`,
       );
       return "submitted";
     }
+    // Direct messages: no gate to await, so claim right before dispatch. (The
+    // group branch claims BEFORE its gate wait so a shutdown-mid-wait cannot lose
+    // the frame under this client's legacy advance-on-write delivery — see
+    // Finding 1 corrected above.)
+    const claimed = claimInboundTurn(turn);
+    if (claimed === "skipped") return "skipped";
     return dispatchTurnToAgent(turn);
   };
 
@@ -2406,6 +2795,20 @@ export async function startOpenclawClawlingGateway(params: StartGatewayParams):
     })();
   });
 
+  // Initial pull of per-group agent settings at startup (best-effort; errors are
+  // logged). `bypassRefresh: true` (Finding 4) keeps this pre-connect pull from
+  // rotating `account.token` out from under the already-constructed WS client.
+  // Settling this releases the Finding-2 group-dispatch gate.
+  pullGroupSettings({ bypassRefresh: true });
+  // Safety: never strand a held group message if the runtime is torn down while a
+  // pull is in flight. `waitWithTimeout` already releases group waiters on abort,
+  // but force the gate open too so any later `wait()` resolves immediately.
+  abortSignal.addEventListener(
+    "abort",
+    () => settingsReadyGate.forceOpen(),
+    { once: true },
+  );
+
   // `client.connect()` resolves on `hello-ok` or rejects on `hello-fail`
   // (auth). Transport failures (server unreachable, DNS error, etc.) do
   // NOT reject this promise — the local client handles them internally and

package/src/storage.ts

@@ -113,6 +113,26 @@ export type FinishConnectionInput = {
   error?: string | null;
 };
 
+/** A row from `clawchat_messages` as returned by `listRecentGroupMessages`. */
+export type MessageRow = {
+  id: number;
+  platform: string;
+  account_id: string;
+  kind: string;
+  direction: string;
+  event_type: string;
+  trace_id: string | null;
+  chat_id: string | null;
+  message_id: string | null;
+  text: string | null;
+  raw_json: string | null;
+  created_at: number;
+  send_status: string | null;
+  protocol_message_id: string | null;
+  acked_at: number | null;
+  send_error: string | null;
+};
+
 export type ToolCallInput = {
   platform: string;
   accountId?: string | null;
@@ -845,6 +865,32 @@ export class ClawChatStore {
     ) ?? [];
   }
 
+  /**
+   * Return the last `limit` user-visible messages in a group chat, ordered
+   * oldest-first. Only `kind = 'message'` rows are returned; internal kinds such
+   * as `'thinking'` are excluded so the @-mention prior-context block never
+   * surfaces the agent's intermediate output as conversation history.
+   * Uses `idx_clawchat_messages_chat_created` for performance.
+   * Returns an empty array if the store is unavailable.
+   */
+  listRecentGroupMessages(
+    platform: string,
+    accountId: string,
+    chatId: string,
+    limit: number,
+  ): MessageRow[] {
+    return this.read(() => {
+      const rows = this.requireDb()
+        .prepare(
+          `SELECT * FROM clawchat_messages
+            WHERE platform = ? AND account_id = ? AND chat_id = ? AND kind = 'message'
+            ORDER BY created_at DESC, rowid DESC LIMIT ?`,
+        )
+        .all(platform, accountId, chatId, limit) as MessageRow[];
+      return rows.reverse(); // oldest-first for prompt order
+    }) ?? [];
+  }
+
   close(): void {
     this.db?.close();
     this.db = null;