openclaw-lark-multi-agent 1.8.4 → 1.8.6

package/dist/openclaw-client.js

@@ -25,6 +25,14 @@ export class SupersededObservation extends Error {
         this.name = "SupersededObservation";
     }
 }
+export class AdmissionUnconfirmed extends Error {
+    submissionId;
+    constructor(submissionId, cause) {
+        super('消息提交结果尚未确认；本地保留原提交身份，不会自动重复发送。', { cause });
+        this.submissionId = submissionId;
+        this.name = 'AdmissionUnconfirmed';
+    }
+}
 export const GATEWAY_PROTOCOL_MIN = 4;
 export const GATEWAY_PROTOCOL_MAX = 4;
 const REQUIRED_GATEWAY_METHODS = [
@@ -74,8 +82,10 @@ export class OpenClawClient {
     /** Deduplicates 2026.8 canonical `agent.stream=tool` events against legacy
      * `stream=item` mirrors when a runtime emits both representations. */
     recentToolEventKeys = new Map();
+    sessionSettlementCallbacks = new Map();
     sessionMessageCallbacks = new Map();
     progressCallbacks = new Map();
+    progressGenerations = new Map();
     /** Live collectReply fences per canonical session key. The most recent
      *  collector for a session owns the shared event bucket; a new batch (or a
      *  queue-custody revocation) fences stale ones synchronously so they cannot
@@ -113,6 +123,8 @@ export class OpenClawClient {
     isExplicitlyStoppedRun(sessionKey, runId) {
         if (!runId)
             return false;
+        if (this.recoveryStore?.isStoppedObservation(this.canonicalSessionKey(sessionKey), runId))
+            return true;
         const key = JSON.stringify([this.canonicalSessionKey(sessionKey), runId]);
         const at = this.explicitlyStoppedRuns.get(key);
         if (at === undefined)
@@ -134,6 +146,89 @@ export class OpenClawClient {
     maintenanceConcurrency = Number(process.env.OPENCLAW_LARK_MULTI_AGENT_MAINTENANCE_CONCURRENCY || 1);
     activeMaintenanceRpcs = 0;
     maintenanceWaiters = [];
+    observationEpoch = new Map();
+    stopGenerations = new Map();
+    recoveryStore;
+    recoveryTimer;
+    recoveryChecking = false;
+    eventCollectors = new Set();
+    forwardedFinals = new Map();
+    /** One paced recovery scheduler for all persisted exact runs. No business
+     * replay, no per-run infinite timers, and each query has its own deadline. */
+    bindRecoveryStore(store) { this.recoveryStore = store; this.scheduleRecovery(); }
+    scheduleRecovery() {
+        if (this.recoveryTimer || !this.shouldReconnect || !this.recoveryStore)
+            return;
+        this.recoveryTimer = setTimeout(() => { this.recoveryTimer = undefined; void this.recoverExactRuns().finally(() => this.scheduleRecovery()); }, 30_000);
+        this.recoveryTimer.unref?.();
+    }
+    async recoverExactRuns() {
+        if (this.recoveryChecking || !this.recoveryStore)
+            return;
+        this.recoveryChecking = true;
+        try {
+            for (const item of this.recoveryStore.listRunObservations(undefined, Date.now(), 20)) {
+                // Advance every selected row, including temporarily unsubscribed/owned
+                // ones, so a due page cannot starve recoverable runs behind it.
+                this.recoveryStore.saveRunObservation(item.sessionKey, item.runId, item, Date.now() + 60_000);
+                if (!this.sessionMessageCallbacks.has(item.sessionKey) && !this.sessionMessageCallbacks.has(this.shortKey(item.sessionKey)))
+                    continue;
+                if (this.ownedDeliveryRuns.has(item.runId))
+                    continue;
+                try {
+                    const snapshot = item.terminalObserved ? { runId: item.runId, status: 'ok', endedAt: Date.now(), terminalReply: { disposition: 'visible', text: item.terminalText } } : await this.rpc('agent.wait', { runId: item.runId, timeoutMs: 1 }, 2500);
+                    if (this.recoveryStore.runObservationState(item.sessionKey, item.runId) !== 'observing' || this.isExplicitlyStoppedRun(item.sessionKey, item.runId) || this.ownedDeliveryRuns.has(item.runId))
+                        continue;
+                    if (snapshot?.runId !== item.runId || !Number.isFinite(snapshot.endedAt) || snapshot.endedAt <= 0 || snapshot.yielded || snapshot.pendingError || ['queue', 'gateway_draining'].includes(snapshot.timeoutPhase) || typeof snapshot.startedAt === 'number' && snapshot.endedAt < snapshot.startedAt)
+                        continue;
+                    const terminal = snapshot.terminalReply;
+                    const callback = this.sessionMessageCallbacks.get(item.sessionKey) || this.sessionMessageCallbacks.get(this.shortKey(item.sessionKey));
+                    if (['error', 'timeout'].includes(snapshot.status)) {
+                        // endedAt + exact run is terminal evidence; bare query timeouts never get here.
+                        await callback?.(String(snapshot.error || snapshot.status), { sourceType: 'run_error', sessionKey: item.sessionKey, runId: item.runId,
+                            error: { sessionKey: item.sessionKey, runId: item.runId, source: 'chat', state: 'error', detail: String(snapshot.error || snapshot.status) } });
+                        this.recoveryStore.finishRunObservation(item.sessionKey, item.runId);
+                        continue;
+                    }
+                    if (snapshot.status !== 'ok' || !['visible', 'silent', 'empty'].includes(terminal?.disposition))
+                        continue;
+                    if (terminal.disposition === 'visible' && typeof terminal.text === 'string' && terminal.text.trim()) {
+                        const callback = this.sessionMessageCallbacks.get(item.sessionKey) || this.sessionMessageCallbacks.get(this.shortKey(item.sessionKey));
+                        await callback?.(terminal.text, { sessionKey: item.sessionKey, runId: item.runId, sessionId: item.sessionId, final: true });
+                    }
+                    if (terminal.disposition !== 'visible') {
+                        this.recoveryStore.settleExactRunReactions(item.sessionKey, item.runId);
+                        this.recoveryStore.finishRunObservation(item.sessionKey, item.runId);
+                        await this.sessionSettlementCallbacks.get(this.canonicalSessionKey(item.sessionKey))?.({ sessionKey: item.sessionKey, runId: item.runId, sessionId: item.sessionId, final: true });
+                    }
+                    // Visible custody ends only when the receiver's durable outbox has
+                    // claimed it. A callback resolving alone is not a delivery receipt.
+                }
+                catch { /* Query failed, not the task. Leave exact custody in SQLite. */ }
+            }
+        }
+        finally {
+            this.recoveryChecking = false;
+        }
+    }
+    bufferEvent(key, event) {
+        let bucket = this.agentEvents.get(key);
+        if (!bucket) {
+            bucket = [];
+            this.agentEvents.set(key, bucket);
+        }
+        bucket.push(event);
+        if (bucket.length > 2048)
+            bucket.splice(0, bucket.length - 2048);
+        if (this.agentEvents.size > 512) {
+            for (const candidate of this.agentEvents.keys()) {
+                if (candidate !== key && !this.sessionCollectorFences.has(this.canonicalSessionKey(candidate))) {
+                    this.agentEvents.delete(candidate);
+                    break;
+                }
+            }
+        }
+    }
     constructor(config) {
         this.config = config;
     }
@@ -250,7 +345,7 @@ export class OpenClawClient {
                             // v4: chat delta events carry deltaText (incremental text chunk)
                             const deltaText = frame.payload?.deltaText;
                             if (deltaText) {
-                                this.agentEvents.get(sk).push({
+                                this.bufferEvent(sk, {
                                     ...frame.payload,
                                     stream: "chatDelta",
                                     data: {
@@ -271,7 +366,7 @@ export class OpenClawClient {
                                 }
                             }
                             // Store as a special chatFinal event (not assistant delta to avoid double-counting)
-                            this.agentEvents.get(sk).push({
+                            this.bufferEvent(sk, {
                                 ...frame.payload,
                                 stream: "chatFinal",
                                 // Only the Gateway chat-final envelope confirms a handoff.
@@ -284,7 +379,7 @@ export class OpenClawClient {
                             // must NOT be silently dropped — otherwise mid-run delta text gets
                             // surfaced as if it were a normal reply and the run neither errors
                             // nor retries. Record it so the collect loop can surface/handle it.
-                            this.agentEvents.get(sk).push({
+                            this.bufferEvent(sk, {
                                 ...frame.payload,
                                 stream: "chatError",
                                 data: { error: frame.payload?.errorMessage || frame.payload?.error || "chat error" },
@@ -292,9 +387,18 @@ export class OpenClawClient {
                         }
                     }
                     else {
-                        this.agentEvents.get(sk).push(frame.payload);
+                        this.bufferEvent(sk, frame.payload);
                     }
                 }
+                if (frame.type === "event" && ["agent", "chat"].includes(frame.event)) {
+                    for (const wake of this.eventCollectors)
+                        wake();
+                    // Bound disconnected/unobserved event buffers. Terminal recovery uses
+                    // exact public agent.wait, never an unbounded transcript cache.
+                    for (const [key, bucket] of this.agentEvents)
+                        if (bucket.length > 2048)
+                            bucket.splice(0, bucket.length - 2048);
+                }
                 if (frame.type === "event" && ["agent", "chat", "session.message"].includes(frame.event)) {
                     for (const observer of this.goEvidenceObservers) {
                         try {
@@ -319,7 +423,7 @@ export class OpenClawClient {
                     if (visibleUserText) {
                         if (!this.agentEvents.has(rawKey))
                             this.agentEvents.set(rawKey, []);
-                        this.agentEvents.get(rawKey).push({
+                        this.bufferEvent(rawKey, {
                             runId: frame.payload.runId,
                             sessionKey: rawKey,
                             stream: "sessionUser",
@@ -335,7 +439,7 @@ export class OpenClawClient {
                     if (visibleAssistantText) {
                         if (!this.agentEvents.has(rawKey))
                             this.agentEvents.set(rawKey, []);
-                        this.agentEvents.get(rawKey).push({
+                        this.bufferEvent(rawKey, {
                             runId: frame.payload.runId,
                             sessionKey: rawKey,
                             stream: "transcriptAssistant",
@@ -343,6 +447,8 @@ export class OpenClawClient {
                         });
                     }
                     this.handleProactiveSessionMessage(rawKey, msg, frame.payload.runId, frame.payload.sessionId);
+                    for (const wake of this.eventCollectors)
+                        wake();
                     // Tool calls in assistant messages — skip, using agent item events instead
                     // (session.message toolCall events are batched, not real-time)
                 }
@@ -675,7 +781,7 @@ export class OpenClawClient {
         const deltaText = !fullText && typeof data.delta === "string" ? data.delta : !fullText && typeof data.deltaText === "string" ? data.deltaText : "";
         const key = rawKey;
         const previous = this.verboseAssistantLatest.get(key) || "";
-        const text = (fullText || (previous + deltaText)).trim();
+        const text = (fullText || (previous + deltaText)).trim().slice(-1024 * 1024);
         if (!text)
             return;
         const now = Date.now();
@@ -720,15 +826,10 @@ export class OpenClawClient {
             console.log(`[OpenClaw] Dropping proactive transcript msg for ${shortKey}; waiting for final delivery path`);
             return false;
         }
-        const cb = this.sessionMessageCallbacks.get(rawKey) || this.sessionMessageCallbacks.get(shortKey);
-        if (cb) {
-            if (runId)
-                cb(proactiveText, { runId, sessionId, sessionKey: this.canonicalSessionKey(rawKey), final: msg?.stopReason === "stop",
-                    ...(!msg?.stopReason && genericFailure(proactiveText) ? { genericErrorCandidate: true } : {}) });
-            else
-                cb(proactiveText);
-        }
-        return Boolean(cb);
+        if (runId && this.isExplicitlyStoppedRun(rawKey, runId))
+            return false;
+        return this.emitProactiveForSession(rawKey, proactiveText, runId ? { runId, sessionId, sessionKey: this.canonicalSessionKey(rawKey), final: msg?.stopReason === 'stop',
+            ...(!msg?.stopReason && genericFailure(proactiveText) ? { genericErrorCandidate: true } : {}) } : undefined);
     }
     scheduleReconnect() {
         const delay = this.reconnectDelay;
@@ -788,12 +889,22 @@ export class OpenClawClient {
             let chatFinalText = "";
             let chatFinalSeen = false;
             let transcriptAssistantText = "";
+            let draftOverflow = false;
+            const boundedDraft = (value) => { if (value.length > 1024 * 1024) {
+                draftOverflow = true;
+                return value.slice(-1024 * 1024);
+            } return value; };
             let sessionKey = targetSessionKey ? `agent:main:${targetSessionKey.replace(/^agent:[^:]+:/, "")}` : "";
             let shortSessionKey = targetSessionKey ? targetSessionKey.replace(/^agent:[^:]+:/, "") : "";
             let chatFinalTimer = null;
             let lifecycleEndTimer = null;
             let replayInvalidTimer = null;
             let genericChatErrorTimer = null;
+            // A channel message-tool send marked terminate=true is the turn's intended
+            // user-visible output (2026-10-16 incident: it bypassed the bridge and the
+            // collector waited forever). Capture its text and settle on a short grace.
+            let terminatingSendText = "";
+            let terminatingSendTimer = null;
             let pendingRuntimeFailureText = "";
             let lastActivitySummary = "";
             let lastActivityAt = 0;
@@ -803,6 +914,7 @@ export class OpenClawClient {
             let anchorSeen = !expectedUserText;
             const activeRunIds = new Set([runId]);
             let preAnchorEvents = [];
+            const foreignUserRuns = new Set();
             const normalizeText = (value) => value.replace(/\s+/g, " ").trim();
             const isExpectedUserText = (value) => {
                 const actual = normalizeText(value);
@@ -832,14 +944,14 @@ export class OpenClawClient {
                     finish(chatFinalText);
                     return;
                 }
-                if (error instanceof SessionWaitPaused && options?.onWaitPaused) {
+                if (error instanceof SessionWaitPaused) {
                     // Foreground notice, background observation. Keep the original queue
                     // owner/progress path so later input still steers into the same run.
                     foregroundPaused = true;
                     if (!waitNoticeSent) {
                         waitNoticeSent = true;
                         try {
-                            await options.onWaitPaused(error);
+                            await options?.onWaitPaused?.(error);
                         }
                         catch {
                             console.warn("[OpenClaw] wait notice delivery pending; observation retained");
@@ -852,8 +964,8 @@ export class OpenClawClient {
                 }
                 reject(error);
             };
-            const checkRunState = async (idleStillCurrent = () => true) => {
-                if (observationClosed || checkingState || Date.now() - lastStateCheckAt < 60_000)
+            const checkRunState = async (idleStillCurrent = () => true, force = false) => {
+                if (observationClosed || checkingState || !force && Date.now() - lastStateCheckAt < 60_000)
                     return;
                 checkingState = true;
                 lastStateCheckAt = Date.now();
@@ -877,7 +989,9 @@ export class OpenClawClient {
                             ? terminal.text
                             : terminal?.disposition === "silent" || terminal?.disposition === "empty"
                                 ? "NO_REPLY"
-                                : this.pickBestCollectedText(chatFinalText, text, chatDeltaText, transcriptAssistantText);
+                                : "";
+                        if (!visible && terminal?.disposition !== "visible")
+                            return;
                         resolve(visible || "NO_REPLY");
                     }
                     else if (snapshot.status === "error" || snapshot.status === "timeout") {
@@ -954,6 +1068,8 @@ export class OpenClawClient {
                 if (activityKeys.has(key))
                     return false;
                 activityKeys.add(key);
+                if (activityKeys.size > 4096)
+                    activityKeys.delete(activityKeys.values().next().value);
                 return true;
             };
             const hasEffectiveActivity = (ev) => {
@@ -986,7 +1102,7 @@ export class OpenClawClient {
                         return false;
                     const previous = activityText.get(source) || "";
                     const next = replace ? chunk : previous + chunk;
-                    activityText.set(source, next);
+                    activityText.set(source, next.slice(-256 * 1024));
                     if (next === previous || (replace && previous.includes(next)))
                         return false;
                     // Replayed replacement snapshots and assistant/chat/transcript mirrors
@@ -1047,6 +1163,12 @@ export class OpenClawClient {
             };
             resetIdleTimer();
             const finish = (finalText) => {
+                if (draftOverflow && finalText !== 'NO_REPLY' && finalText !== chatFinalText) {
+                    // Never publish a truncated accumulator. Keep exact result custody
+                    // until authoritative root terminalReply or full root chat final.
+                    void checkRunState(() => true, true);
+                    return;
+                }
                 clearTimeout(idleTimer);
                 clearInterval(poller);
                 if (chatFinalTimer)
@@ -1057,6 +1179,8 @@ export class OpenClawClient {
                     clearTimeout(replayInvalidTimer);
                 if (genericChatErrorTimer)
                     clearTimeout(genericChatErrorTimer);
+                if (terminatingSendTimer)
+                    clearTimeout(terminatingSendTimer);
                 resolve(finalText);
             };
             const collectEvents = () => {
@@ -1066,36 +1190,18 @@ export class OpenClawClient {
                 // never deliver a reply on this connection, so stop waiting instead of
                 // hanging until the idle timeout. Failing fast lets the bridge
                 // release its busy lock so new messages are not stuck "waiting".
-                if (startedConnected && !this.connected) {
-                    clearInterval(poller);
-                    if (chatFinalTimer)
-                        clearTimeout(chatFinalTimer);
-                    if (lifecycleEndTimer)
-                        clearTimeout(lifecycleEndTimer);
-                    if (replayInvalidTimer)
-                        clearTimeout(replayInvalidTimer);
-                    if (genericChatErrorTimer)
-                        clearTimeout(genericChatErrorTimer);
-                    if (idleTimer)
-                        clearTimeout(idleTimer);
-                    const salvaged = this.pickBestCollectedText(chatFinalText, text, chatDeltaText, transcriptAssistantText);
-                    if (salvaged) {
-                        resolve(salvaged);
-                        return;
-                    }
-                    reject(new Error("Gateway disconnected during run"));
-                    return;
-                }
+                // A disconnect is an observation gap, not an execution failure. The
+                // connection resubscribes and the paced exact-run query reconciles it.
                 // /stop force-abort: finish immediately instead of waiting for the
                 // cancelled lifecycle to be treated as a transient state (idle timeout).
                 if (sessionKey && (this.forceAbortedSessions.has(sessionKey) || this.forceAbortedSessions.has(shortSessionKey))) {
                     this.forceAbortedSessions.delete(sessionKey);
                     this.forceAbortedSessions.delete(shortSessionKey);
-                    finish(text || chatDeltaText || chatFinalText || transcriptAssistantText || "NO_REPLY");
+                    finish("NO_REPLY");
                     return;
                 }
                 const bucketsToScan = sessionKey
-                    ? Array.from(new Set([sessionKey, shortSessionKey].filter(Boolean)))
+                    ? Array.from(new Set([sessionKey, shortSessionKey, ...[...this.agentEvents.keys()].filter(k => this.shortKey(k) === shortSessionKey && this.agentEvents.get(k)?.some(ev => activeRunIds.has(ev.runId)))].filter(Boolean)))
                     : Array.from(this.agentEvents.keys());
                 for (const bucketKey of bucketsToScan) {
                     const bucket = this.agentEvents.get(bucketKey);
@@ -1105,17 +1211,26 @@ export class OpenClawClient {
                     while (i < bucket.length) {
                         const ev = bucket[i];
                         const evRunId = typeof ev.runId === "string" ? ev.runId : "";
-                        const eventSessionMatches = Boolean(sessionKey && (ev.sessionKey === sessionKey || ev.sessionKey === targetSessionKey || ev.sessionKey === shortSessionKey));
+                        const eventSessionMatches = Boolean(sessionKey && (ev.sessionKey === sessionKey || ev.sessionKey === targetSessionKey || ev.sessionKey === shortSessionKey || activeRunIds.has(evRunId) && this.shortKey(ev.sessionKey || '') === shortSessionKey));
                         const matchesRun = evRunId ? activeRunIds.has(evRunId) : false;
                         if (options?.exactRunIdentity && !matchesRun) {
                             i++;
                             continue;
                         }
+                        if (evRunId && foreignUserRuns.has(evRunId)) {
+                            i++;
+                            continue;
+                        }
                         if (!sessionKey && ev.sessionKey) {
                             shortSessionKey = String(ev.sessionKey).replace(/^agent:[^:]+:/, "");
                             sessionKey = `agent:main:${shortSessionKey}`;
                         }
                         if (eventSessionMatches && ev.stream === "sessionUser") {
+                            if (anchorSeen && evRunId && !matchesRun) {
+                                foreignUserRuns.add(evRunId);
+                                i++;
+                                continue;
+                            }
                             bucket.splice(i, 1);
                             if (!anchorSeen && isExpectedUserText(ev.data?.text || "")) {
                                 anchorSeen = true;
@@ -1153,6 +1268,8 @@ export class OpenClawClient {
                         if (eventSessionMatches && expectedUserText && !anchorSeen && !matchesRun) {
                             bucket.splice(i, 1);
                             preAnchorEvents.push(ev);
+                            if (preAnchorEvents.length > 2048)
+                                preAnchorEvents.splice(0, preAnchorEvents.length - 2048);
                             if (preAnchorEvents.length > 200)
                                 preAnchorEvents.shift();
                             continue;
@@ -1189,9 +1306,54 @@ export class OpenClawClient {
                             continue;
                         }
                         bucket.splice(i, 1);
+                        // Continuation progress is valid, but only the admitted root's
+                        // committed terminalReply can authorize another run's final text.
+                        if (evRunId && evRunId !== runId && (ev.stream === 'chatFinal' || ev.stream === 'chatError' || ev.stream === 'lifecycle' && ['end', 'error'].includes(ev.data?.phase))) {
+                            if (ev.stream === 'chatFinal' && ev.data?.gatewayYielded === true)
+                                continue;
+                            void checkRunState(() => true, true);
+                            continue;
+                        }
                         if (hasEffectiveActivity(ev))
                             resetIdleTimer();
                         rememberActivity(ev);
+                        // Terminating channel-send detection: a message-tool result carrying
+                        // terminate=true ends the turn with that send as its user-visible
+                        // output. The bridge is the delivery channel for LMA sessions, so
+                        // waiting for a further final would hang forever (2026-10-16 frozen
+                        // card incident). Capture the sent text at tool start; settle on a
+                        // short grace unless a real final arrives first.
+                        {
+                            const tdata = ev.data || {};
+                            if (ev.stream === "tool" || (ev.stream === "item" && tdata.kind === "tool")) {
+                                const toolName = String(tdata.name || tdata.toolName || "");
+                                const tphase = tdata.phase === "result" ? (tdata.isError || tdata.error ? "error" : "end") : tdata.phase;
+                                if (toolName === "message" && tphase === "start") {
+                                    const raw = tdata.input ?? tdata.args ?? tdata.meta ?? null;
+                                    if (raw !== null) {
+                                        try {
+                                            const parsed = typeof raw === "string" ? JSON.parse(raw) : raw;
+                                            if (parsed && typeof parsed.message === "string" && parsed.message.trim())
+                                                terminatingSendText = parsed.message;
+                                        }
+                                        catch { /* non-JSON tool input */ }
+                                    }
+                                }
+                                else if (toolName === "message" && (tphase === "end" || tphase === "error")) {
+                                    const out = String(JSON.stringify(tdata.output ?? tdata.result ?? tdata.error ?? ""));
+                                    if (/"?terminate"?\s*[:=]\s*true/i.test(out) && !terminatingSendTimer) {
+                                        terminatingSendTimer = setTimeout(() => {
+                                            terminatingSendTimer = null;
+                                            if (observationClosed)
+                                                return;
+                                            const best = (chatFinalText.trim() || text.trim() || terminatingSendText || "").trim();
+                                            finish(best || "NO_REPLY");
+                                        }, 10_000);
+                                        terminatingSendTimer.unref?.();
+                                    }
+                                }
+                            }
+                        }
                         // If more events arrive after a replay-invalid lifecycle end, that lifecycle
                         // was not terminal for the user-visible run. Keep waiting for the real final.
                         if (replayInvalidTimer) {
@@ -1209,30 +1371,30 @@ export class OpenClawClient {
                             lifecycleStartedLogged = true;
                             console.log(`[OpenClaw] lifecycle start for runId=${runId} after ${Date.now() - collectStartedAt}ms`);
                         }
-                        if ((ev.stream === "assistant" || ev.stream === "chatDelta" || ev.stream === "transcriptAssistant") && (ev.data?.deltaText || ev.data?.delta)) {
+                        if ((!evRunId || evRunId === runId) && (ev.stream === "assistant" || ev.stream === "chatDelta" || ev.stream === "transcriptAssistant") && (ev.data?.deltaText || ev.data?.delta)) {
                             const chunk = ev.data.deltaText || ev.data.delta;
                             if (ev.stream === "assistant") {
                                 if (ev.data?.replace) {
-                                    text = chunk;
+                                    text = boundedDraft(chunk);
                                 }
                                 else {
-                                    text += chunk;
+                                    text = boundedDraft(text + chunk);
                                 }
                             }
                             else if (ev.stream === "chatDelta") {
                                 if (ev.data?.replace) {
-                                    chatDeltaText = chunk;
+                                    chatDeltaText = boundedDraft(chunk);
                                 }
                                 else {
-                                    chatDeltaText += chunk;
+                                    chatDeltaText = boundedDraft(chatDeltaText + chunk);
                                 }
                             }
                             else {
                                 if (ev.data?.replace) {
-                                    transcriptAssistantText = chunk;
+                                    transcriptAssistantText = boundedDraft(chunk);
                                 }
                                 else {
-                                    transcriptAssistantText += chunk;
+                                    transcriptAssistantText = boundedDraft(transcriptAssistantText + chunk);
                                 }
                             }
                         }
@@ -1258,8 +1420,7 @@ export class OpenClawClient {
                                 // Finish scanning this batch first so an already-arrived real
                                 // final/error wins over a stale waiting notice. No status RPC
                                 // (or ten-minute silence) is needed to confirm this wire fact.
-                                if (options?.onWaitPaused)
-                                    void Promise.resolve().then(() => handleTimeoutResult(new SessionWaitPaused(normalizeSessionRuntimeStatus(undefined), false, "yield")));
+                                void Promise.resolve().then(() => handleTimeoutResult(new SessionWaitPaused(normalizeSessionRuntimeStatus(undefined), false, "yield")));
                                 continue;
                             }
                             chatFinalText = ev.data?.text || "";
@@ -1275,10 +1436,6 @@ export class OpenClawClient {
                                     // emit only partial deltas (e.g. "N") while final contains "NO_REPLY".
                                     const latestFinalText = this.pickBestCollectedText(chatFinalText, text, chatDeltaText, transcriptAssistantText);
                                     // Never abort a yielded original run, nor an empty final.
-                                    if (!foregroundYielded && latestFinalText)
-                                        this.abortChat(targetSessionKey || sessionKey, runId).catch((err) => {
-                                            console.warn(`[OpenClaw] abort after chatFinal fallback failed:`, safeErrorSummary(err));
-                                        });
                                     if (latestFinalText) {
                                         finish(latestFinalText);
                                     }
@@ -1468,7 +1625,19 @@ export class OpenClawClient {
                     }
                 }
             };
-            const poller = setInterval(collectEvents, 50);
+            let poller;
+            const poll = () => {
+                collectEvents();
+                if (!observationClosed) {
+                    const quiet = Date.now() - (lastActivityAt || collectStartedAt);
+                    poller = setTimeout(poll, !startedConnected || quiet < 1000 ? 50 : quiet < 10_000 ? 1000 : 30_000);
+                    poller.unref?.();
+                }
+            };
+            poller = setTimeout(poll, 50);
+            const wakeCollector = () => { if (!observationClosed)
+                collectEvents(); };
+            this.eventCollectors.add(wakeCollector);
             const observationKey = targetSessionKey ? this.canonicalSessionKey(targetSessionKey) : "";
             const checkAfterNoActiveRun = async () => {
                 await checkRunState();
@@ -1487,13 +1656,10 @@ export class OpenClawClient {
             };
             if (observationKey)
                 this.runStateChecks.set(observationKey, checkAfterNoActiveRun);
-            // Bound local resources without cancelling an execution we cannot prove stuck.
-            const observationHorizon = setTimeout(() => reject(new Error("LMA 本地监听达到 24 小时上限，结果未确认；未发送停止请求，请检查原运行。")), 24 * 60 * 60_000);
-            observationHorizon.unref?.();
             cleanupObservation = () => {
                 observationClosed = true;
                 clearTimeout(idleTimer);
-                clearTimeout(observationHorizon);
+                this.eventCollectors.delete(wakeCollector);
                 clearInterval(poller);
                 if (chatFinalTimer)
                     clearTimeout(chatFinalTimer);
@@ -1503,6 +1669,8 @@ export class OpenClawClient {
                     clearTimeout(replayInvalidTimer);
                 if (genericChatErrorTimer)
                     clearTimeout(genericChatErrorTimer);
+                if (terminatingSendTimer)
+                    clearTimeout(terminatingSendTimer);
                 if (observationKey && this.runStateChecks.get(observationKey) === checkAfterNoActiveRun)
                     this.runStateChecks.delete(observationKey);
             };
@@ -1513,6 +1681,9 @@ export class OpenClawClient {
             const fenceSuperseded = () => {
                 if (observationClosed)
                     return;
+                // Atomic custody transfer BEFORE closing the old consumer; a final
+                // arriving in this tick is immediately eligible for exact proactive.
+                this.releasePausedWait(runId);
                 cleanupObservation();
                 reject(new SupersededObservation());
             };
@@ -1655,47 +1826,52 @@ export class OpenClawClient {
     async injectAssistantMessage(params) {
         return this.rpc("chat.inject", { ...params, sessionKey: this.canonicalSessionKey(params.sessionKey) }, 10000);
     }
-    /**
-     * Submit a mid-run message through the lma-steer plugin.
-     *
-     * OpenClaw's public `chat.send { queueMode: "steer" }` returns `started` even
-     * when it falls through to a later ordinary run; it therefore cannot tell the
-     * bridge whether THIS message entered the active run. The plugin resolves the
-     * active embedded run and reports `steered` only when it actually queued there.
-     * A matching session.message remains the final consumption confirmation.
-     *
-     * If the plugin is missing, stale, or rejects the injection, return unavailable
-     * and let LMA's durable trigger run normally after the current turn. Never use
-     * the ambiguous public admission as a realtime-insertion success signal.
-     */
-    async steer(sessionKey, text, displayText) {
-        const key = this.canonicalSessionKey(sessionKey);
-        // Consumption can arrive before the plugin RPC response at a tool boundary.
-        const cancelPending = this.registerPendingSteer(key, text, displayText);
+    /** Real-time session input uses the coordinated plugin's durable callback
+     * receipt protocol. SDK eligibility/text mirrors never prove acceptance;
+     * missing/legacy plugin observations stay pending without blind mutation. */
+    async exactRunSettled(runId) {
         try {
-            const res = await this.rpc("lma.steer", { sessionKey: key, text }, 10000);
-            if (res?.status !== "steered") {
-                // A locally busy collector can outlive the actual Gateway turn. Check
-                // its exact terminal record now, rather than parking input for 30 min.
-                if (res?.status === "no_active_run")
-                    await this.runStateChecks.get(key)?.();
-                if (res?.status && res.status !== "no_active_run") {
-                    console.warn(`[OpenClaw] lma.steer ${res.status} for ${key.slice(-8)}`);
-                }
-                cancelPending();
-                // Pass the gateway's authoritative "no active run" verdict through: the
-                // caller uses it to detect a zombie queue owner (2026-10-15 incident).
-                if (res?.status === "no_active_run")
-                    return { status: "no_active_run" };
-                return { status: "unavailable" };
-            }
-            return { status: "steered", cancelPending };
+            const r = await this.rpc('agent.wait', { runId, timeoutMs: 1 }, 2500);
+            return r?.runId === runId && !r.pendingError && !r.yielded && ['ok', 'error', 'timeout'].includes(r.status) && Number.isFinite(r.endedAt) && r.endedAt > 0 && (r.status !== 'ok' || ['visible', 'silent', 'empty'].includes(r.terminalReply?.disposition));
         }
-        catch (err) {
-            cancelPending();
-            const message = err?.message || String(err);
-            console.warn(`[OpenClaw] lma.steer unavailable for ${key.slice(-8)}: ${message}`);
-            return { status: "unavailable" };
+        catch {
+            return false;
+        }
+    }
+    async cancelSteerSession(sessionKey, stopEpoch) {
+        await this.rpc('lma.steer.stop', { sessionKey: this.canonicalSessionKey(sessionKey), stopEpoch }, 2500);
+    }
+    async steer(sessionKey, text, displayText, identity) {
+        if (!identity?.insertionId || !identity.expectedRunId)
+            return { status: 'pending', attempted: false, reason: 'exact target not admitted yet' };
+        let attempted = false;
+        const base = { insertionId: identity.insertionId, expectedRunId: identity.expectedRunId, sessionId: identity.expectedSessionId };
+        try {
+            const capability = await this.rpc('lma.steer.capabilities', {}, 2500);
+            // This is an LMA protocol-version check, NOT a fictitious source-CAS
+            // requirement. Builtin callbacks can be used with atomicRunBound=false.
+            if (capability?.protocol !== 2 || capability?.durableAttempts !== true || capability?.acceptanceCallback !== true)
+                return { ...base, status: 'unavailable', attempted: identity.queryOnly === true, reason: 'Update the coordinated LMA plugin; legacy booleans are not acceptance receipts' };
+            const info = await this.getSessionStatus(sessionKey);
+            const currentId = info?.session?.sessionId;
+            if (info?.session?.archived === true || (identity.expectedSessionId && currentId && currentId !== identity.expectedSessionId))
+                return { ...base, status: 'target_changed', attempted: identity.queryOnly === true, reason: 'session archived or generation changed; no automatic migration' };
+            if (!currentId)
+                return { ...base, status: 'pending', attempted: identity.queryOnly === true, reason: 'session generation observation unavailable' };
+            base.sessionId = currentId;
+            attempted = true;
+            const result = await this.rpc('lma.steer', { sessionKey: this.canonicalSessionKey(sessionKey), text, ...identity,
+                expectedSessionId: identity.expectedSessionId || currentId, stopEpoch: identity.stopEpoch ?? 0 }, 2500);
+            if (result?.insertionId !== identity.insertionId || result?.expectedRunId !== identity.expectedRunId || result?.sessionId !== currentId ||
+                !['pending', 'accepted', 'rejected', 'unknown', 'target_changed', 'target_ended', 'stopped'].includes(result.status))
+                return { ...base, status: 'unknown', attempted: true, reason: 'Invalid or legacy plugin receipt; not replayed' };
+            if (result.status === 'pending' && result.attempted === false && result.reason === 'target_not_ready')
+                await this.runStateChecks.get(this.canonicalSessionKey(sessionKey))?.();
+            return result;
+        }
+        catch (error) {
+            return { ...base, status: attempted ? 'unknown' : 'pending', attempted: attempted || identity.queryOnly === true,
+                reason: attempted ? 'Insertion receipt unknown; query stable identity only' : 'Readiness observation unavailable; retained for paced recovery' };
         }
     }
     /** Callbacks fired when a steered message is confirmed consumed by the model
@@ -1705,8 +1881,8 @@ export class OpenClawClient {
      *  Callbacks are one-shot: returning true removes them. */
     steerConsumedCallbacks = new Map();
     /** Register a callback (per bare session key) invoked when a steered message
-     *  is actually consumed by the active run. The bridge uses this to flip the
-     *  Feishu reaction from "Typing" (awaiting insertion) to "Get" (inserted).
+     *  is actually consumed by the active run. This legacy text observer is
+     *  presentation-only; it cannot authorize a receipt reaction.
      *  Return true from the callback to consume/remove it (one-shot). */
     onSteerConsumed(sessionKey, matchText, cb) {
         const key = this.shortKey(sessionKey);
@@ -1848,6 +2024,7 @@ export class OpenClawClient {
      *  stale poller cannot steal the replacement batch's frames (2026-10-16). */
     revokeSessionCollectors(sessionKey, reason) {
         const key = this.canonicalSessionKey(sessionKey);
+        this.observationEpoch.set(key, (this.observationEpoch.get(key) || 0) + 1);
         const fences = this.sessionCollectorFences.get(key);
         if (!fences || fences.size === 0)
             return 0;
@@ -2070,6 +2247,9 @@ export class OpenClawClient {
         // chat.abort supports { sessionKey } with no runId to abort ALL active runs
         // for that session. Used by /stop to force-clear a stuck run.
         if (!runId) {
+            this.stopGenerations.set(key, (this.stopGenerations.get(key) || 0) + 1);
+            this.revokeSessionCollectors(key, 'explicit stop');
+            this.recoveryStore?.stopSessionObservations(key);
             for (const [identity, at] of this.explicitlyStoppedRuns)
                 if (Date.now() - at > 24 * 60 * 60_000)
                     this.explicitlyStoppedRuns.delete(identity);
@@ -2094,6 +2274,7 @@ export class OpenClawClient {
                 for (const stopped of result.runIds)
                     if (typeof stopped === "string" && stopped) {
                         this.explicitlyStoppedRuns.set(JSON.stringify([key, stopped]), Date.now());
+                        this.recoveryStore?.stopExactRun(key, stopped);
                     }
             }
             return result;
@@ -2119,6 +2300,8 @@ export class OpenClawClient {
             // still reach the proactive callback.
             return;
         }
+        if (runId && this.isExplicitlyStoppedRun(sessionKey, runId) && state === 'final')
+            return;
         const stopReason = [payload?.stopReason, payload?.message?.stopReason].find(reason => reason === "error" || reason === "aborted")
             || payload?.stopReason || payload?.message?.stopReason;
         const isError = state === "error" || state === "aborted" || stopReason === "error" || stopReason === "aborted";
@@ -2163,11 +2346,31 @@ export class OpenClawClient {
         return parts.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n").trim();
     }
     emitProactiveForSession(sessionKey, text, meta) {
-        const [shortKey, fullKey] = this.sessionKeyVariants(sessionKey);
-        const cb = this.sessionMessageCallbacks.get(fullKey) || this.sessionMessageCallbacks.get(shortKey);
-        if (!cb)
+        const keys = this.sessionKeyVariants(sessionKey);
+        const callback = keys.map(k => this.sessionMessageCallbacks.get(k)).find(Boolean);
+        if (!callback)
             return false;
-        cb(text, meta);
+        const identity = meta?.final && meta.runId ? JSON.stringify([this.canonicalSessionKey(sessionKey), meta.runId]) : '';
+        const fingerprint = createHash('sha256').update(text).digest('hex');
+        if (identity && this.forwardedFinals.get(identity) === fingerprint)
+            return true;
+        if (identity) {
+            this.forwardedFinals.set(identity, fingerprint);
+            if (this.forwardedFinals.size > 2048)
+                this.forwardedFinals.delete(this.forwardedFinals.keys().next().value);
+        }
+        if (identity)
+            this.recoveryStore?.saveRunObservation(this.canonicalSessionKey(sessionKey), meta.runId, { sessionId: meta?.sessionId, terminalText: text, terminalObserved: true }, Date.now() + 60_000);
+        try {
+            const result = meta ? callback(text, meta) : callback(text);
+            if (identity)
+                void Promise.resolve(result).catch(() => this.forwardedFinals.delete(identity));
+        }
+        catch (error) {
+            if (identity)
+                this.forwardedFinals.delete(identity);
+            throw error;
+        }
         return true;
     }
     suppressSessionKeys(keys) {
@@ -2421,31 +2624,44 @@ export class OpenClawClient {
     async chatSend(params) {
         const sk = this.shortKey(params.sessionKey);
         const fullSessionKey = this.canonicalSessionKey(params.sessionKey);
+        const generation = (this.observationEpoch.get(fullSessionKey) || 0) + 1;
+        this.observationEpoch.set(fullSessionKey, generation);
+        const stopGeneration = this.stopGenerations.get(fullSessionKey) || 0;
+        const isCurrent = () => this.observationEpoch.get(fullSessionKey) === generation && (this.stopGenerations.get(fullSessionKey) || 0) === stopGeneration;
+        const assertCurrent = () => { if (!isCurrent())
+            throw new SupersededObservation('admission generation revoked'); };
         this.clearVerboseAssistantState(sk);
+        const submissionId = randomUUID();
         let ownedRunId = "";
         let waitPaused = false;
         try {
-            // Drop stale buffered events for this session before starting a new run.
-            // This prevents an old final text (e.g. previous "ok") from being consumed by
-            // the next message while still allowing sessionKey matching for internal runIds.
-            this.agentEvents.set(fullSessionKey, []);
-            this.agentEvents.set(sk, []);
+            // New user inputs arriving after /stop are admitted only AFTER that
+            // authorized session-wide abort returns. They are not part of its cutoff.
+            const stopBarrier = this.pendingExplicitStops.get(fullSessionKey);
+            if (stopBarrier)
+                await stopBarrier;
+            assertCurrent();
             const releaseChatSendSlot = await this.acquireChatSendSlot();
             let result;
             const sendStartedAt = Date.now();
             try {
-                // A stale collector from a previous batch must not steal this batch's
-                // frames from the shared session bucket (2026-10-16 regression). Fence
-                // any still-live local observation BEFORE issuing chat.send.
-                this.revokeSessionCollectors(sk, "new chat.send supersedes stale observation");
-                await params.onSendAttempt?.();
-                const sendChat = () => this.rpc("chat.send", {
-                    sessionKey: this.canonicalSessionKey(sk),
-                    message: params.message,
-                    attachments: params.attachments,
-                    deliver: params.deliver ?? false,
-                    idempotencyKey: randomUUID(),
-                });
+                assertCurrent();
+                this.recoveryStore?.saveAdmission(fullSessionKey, submissionId, 'reserved', { generation, stopGeneration });
+                await params.onSendAttempt?.(submissionId);
+                assertCurrent();
+                const idempotencyKey = submissionId;
+                const sendChat = () => {
+                    assertCurrent();
+                    this.recoveryStore?.saveAdmission(fullSessionKey, idempotencyKey, 'dispatching', { generation, stopGeneration, payloadDigest: createHash('sha256').update(params.message).digest('hex') });
+                    this.recoveryStore?.saveRunObservation(fullSessionKey, submissionId, { admissionOnly: true }, Date.now() + 30_000);
+                    return this.rpc("chat.send", {
+                        sessionKey: this.canonicalSessionKey(sk),
+                        message: params.message,
+                        attachments: params.attachments,
+                        deliver: params.deliver ?? false,
+                        idempotencyKey,
+                    });
+                };
                 try {
                     result = await sendChat();
                 }
@@ -2453,8 +2669,15 @@ export class OpenClawClient {
                     // The Gateway auto-archives sessions past the active-session cap; an
                     // archived session refuses new work. Restore it once and retry — the
                     // user should never have to fix this by hand.
-                    if (!this.isArchivedSessionError(err))
-                        throw err;
+                    if (!this.isArchivedSessionError(err)) {
+                        const rejected = err instanceof Error && /^RPC error:/.test(err.message);
+                        this.recoveryStore?.saveAdmission(fullSessionKey, idempotencyKey, rejected ? 'rejected' : 'unknown', { generation, stopGeneration });
+                        if (rejected) {
+                            this.recoveryStore?.finishRunObservation(fullSessionKey, submissionId, 'rejected');
+                            throw err;
+                        }
+                        throw new AdmissionUnconfirmed(idempotencyKey, err);
+                    }
                     console.warn(`[OpenClaw] chat.send hit archived session for ${sk}; restoring and retrying once`);
                     const restored = await this.unarchiveSession(sk);
                     if (!restored)
@@ -2466,18 +2689,49 @@ export class OpenClawClient {
                 releaseChatSendSlot();
             }
             ownedRunId = typeof result?.runId === "string" ? result.runId : "";
+            if (!ownedRunId)
+                throw new AdmissionUnconfirmed('unidentified-receipt');
+            this.recoveryStore?.saveAdmission(fullSessionKey, submissionId, ['started', 'ok'].includes(result.status) ? 'accepted' : 'unconfirmed', { generation, stopGeneration, runId: ownedRunId });
+            if (ownedRunId !== submissionId)
+                this.recoveryStore?.finishRunObservation(fullSessionKey, submissionId, 'identified');
+            this.recoveryStore?.saveRunObservation(fullSessionKey, ownedRunId, { sessionId: result.sessionId });
+            if (this.isExplicitlyStoppedRun(fullSessionKey, ownedRunId) || (this.stopGenerations.get(fullSessionKey) || 0) !== stopGeneration) {
+                this.recoveryStore?.finishRunObservation(fullSessionKey, ownedRunId, 'stopped');
+                throw new SupersededObservation('late stopped admission');
+            }
+            if (!isCurrent())
+                throw new SupersededObservation('late admission is not current');
+            // Commit replacement only AFTER confirmed admission. A failed new send
+            // must leave the healthy old collector and its custody intact.
+            const previous = this.sessionCollectorFences.get(fullSessionKey);
+            if (previous)
+                for (const fence of [...previous])
+                    fence();
             this.ownDeliveryRun(ownedRunId);
             console.log(`[OpenClaw] chat.send runId: ${result.runId} (rpc=${Date.now() - sendStartedAt}ms, attachments=${params.attachments?.length || 0})`);
-            await params.onSubmitted?.(result.runId);
+            await params.onRunIdentified?.(result.runId);
+            assertCurrent();
+            // A reservation/in_flight reply is not confirmed acceptance. Keep UI
+            // Typing while exact collection/read-only receipt reconciliation proceeds.
+            if (result.status === 'started' || result.status === 'ok' || Number.isSafeInteger(result.messageSeq) && result.messageSeq >= 0)
+                await params.onSubmitted?.(result.runId);
+            assertCurrent();
             if (params.onProgress) {
                 this.progressCallbacks.set(sk, params.onProgress);
                 this.progressCallbacks.set(fullSessionKey, params.onProgress);
+                this.progressGenerations.set(sk, generation);
+                this.progressGenerations.set(fullSessionKey, generation);
                 void params.onProgress({ kind: "lifecycle", text: "等待 OpenClaw 回复" });
             }
-            return await this.collectReply(result.runId, params.timeoutMs || FOREGROUND_WAIT_MS, sk, { emptyFinalAsNoReply: params.emptyFinalAsNoReply, expectedUserText: params.message, onWaitPaused: params.onWaitPaused });
+            const reply = await this.collectReply(result.runId, params.timeoutMs || FOREGROUND_WAIT_MS, sk, { emptyFinalAsNoReply: params.emptyFinalAsNoReply, expectedUserText: params.message, onWaitPaused: params.onWaitPaused });
+            if (reply.trim().toUpperCase() === 'NO_REPLY')
+                this.recoveryStore?.finishRunObservation(fullSessionKey, ownedRunId);
+            else
+                this.recoveryStore?.saveRunObservation(fullSessionKey, ownedRunId, { sessionId: result.sessionId, terminalText: reply, terminalObserved: true }, Date.now() + 30_000);
+            return reply;
         }
         catch (error) {
-            waitPaused = error instanceof SessionWaitPaused;
+            waitPaused = error instanceof SessionWaitPaused || error instanceof SupersededObservation;
             throw error;
         }
         finally {
@@ -2489,10 +2743,14 @@ export class OpenClawClient {
             // progress callback (the fence settles the old promise after the new
             // batch may already have registered its own callback).
             if (params.onProgress) {
-                if (this.progressCallbacks.get(sk) === params.onProgress)
+                if (this.progressGenerations.get(sk) === generation && this.progressCallbacks.get(sk) === params.onProgress) {
                     this.progressCallbacks.delete(sk);
-                if (this.progressCallbacks.get(fullSessionKey) === params.onProgress)
+                    this.progressGenerations.delete(sk);
+                }
+                if (this.progressGenerations.get(fullSessionKey) === generation && this.progressCallbacks.get(fullSessionKey) === params.onProgress) {
                     this.progressCallbacks.delete(fullSessionKey);
+                    this.progressGenerations.delete(fullSessionKey);
+                }
             }
             if (waitPaused)
                 this.releasePausedWait(ownedRunId);
@@ -2548,6 +2806,7 @@ export class OpenClawClient {
                 emptyFinalAsNoReply: params.emptyFinalAsNoReply,
                 onSendAttempt: params.onSendAttempt,
                 onSubmitted: params.onSubmitted,
+                onRunIdentified: params.onRunIdentified,
                 onProgress: params.onProgress,
                 onWaitPaused: params.onWaitPaused,
             });
@@ -2585,6 +2844,7 @@ export class OpenClawClient {
             emptyFinalAsNoReply: params.emptyFinalAsNoReply,
             onSendAttempt: params.onSendAttempt,
             onSubmitted: params.onSubmitted,
+            onRunIdentified: params.onRunIdentified,
             onProgress: params.onProgress,
             onWaitPaused: params.onWaitPaused,
         });
@@ -2683,6 +2943,11 @@ export class OpenClawClient {
     }
     async disconnect() {
         this.shouldReconnect = false;
+        for (const key of [...this.sessionCollectorFences.keys()])
+            this.revokeSessionCollectors(key, 'bridge disconnected; durable exact observation retained');
+        if (this.recoveryTimer)
+            clearTimeout(this.recoveryTimer);
+        this.recoveryTimer = undefined;
         for (const timer of this.suppressedSessionTimers.values())
             clearTimeout(timer);
         this.suppressedSessionTimers.clear();
@@ -2715,8 +2980,10 @@ export class OpenClawClient {
      * Subscribe to message events for a session.
      * When the agent proactively produces a message, the callback fires.
      */
-    async subscribeSession(sessionKey, onMessage) {
+    async subscribeSession(sessionKey, onMessage, onSettled) {
         // Register under both the short key and the full key with agent:main: prefix
+        if (onSettled)
+            this.sessionSettlementCallbacks.set(this.canonicalSessionKey(sessionKey), onSettled);
         this.sessionMessageCallbacks.set(sessionKey, onMessage);
         this.sessionMessageCallbacks.set(`agent:main:${sessionKey}`, onMessage);
         this.subscribedKeys.add(sessionKey);
@@ -2739,6 +3006,7 @@ export class OpenClawClient {
             this.clearVerboseAssistantState(sessionKey);
     }
     async unsubscribeSession(sessionKey) {
+        this.sessionSettlementCallbacks.delete(this.canonicalSessionKey(sessionKey));
         this.sessionMessageCallbacks.delete(sessionKey);
         this.sessionMessageCallbacks.delete(`agent:main:${sessionKey}`);
         this.toolEventCallbacks.delete(sessionKey);