openclaw-lark-multi-agent 1.4.12 → 1.5.0

package/dist/message-store.d.ts

@@ -1,3 +1,4 @@
+import { type ErrorProvenance, type ErrorVerdict } from "./terminal-errors.js";
 export type BotChatMode = "normal" | "free" | "mute";
 export interface ChatInfo {
     chatId: string;
@@ -60,9 +61,38 @@ export interface DeliveryOutboxItem {
     createdAt: number;
     updatedAt: number;
 }
+export interface PendingErrorNotice {
+    botName: string;
+    chatId: string;
+    noticeId: string;
+    provenance: ErrorProvenance;
+    checks: number;
+    nextCheckAt: number;
+    createdAt: number;
+    status: "pending" | "parked" | "terminal" | "suppressed" | "stopped";
+    verdict?: ErrorVerdict;
+    hasObservedContinuingTask?: boolean;
+    recoveryProbeUsed?: boolean;
+}
 export declare class MessageStore {
     private db;
     constructor(dbPath?: string);
+    observeRunError(botName: string, chatId: string, provenance: ErrorProvenance): PendingErrorNotice;
+    getErrorNotice(botName: string, chatId: string, noticeId: string): PendingErrorNotice | undefined;
+    saveErrorNotice(record: PendingErrorNotice): void;
+    listPendingErrorNotices(botName: string, chatId: string): PendingErrorNotice[];
+    /** A later exact final may be content-deduped against its own transcript.
+     * Upgrade only identical payloads with the same canonical session/run; never
+     * infer identity from text similarity or another run's successful answer. */
+    promoteExactRunFinal(botName: string, chatId: string, sessionKey: string, runId: string, contentHash: string, content: string, attachmentsJson: string): void;
+    hasExactRunFinalPayload(botName: string, chatId: string, p: {
+        sessionKey: string;
+        runId: string;
+    }, content: string, attachmentsJson: string): boolean;
+    hasRunFinalDelivery(botName: string, chatId: string, p: ErrorProvenance, confirmed: boolean): boolean;
+    renewUnsentErrorDelivery(id: number, content: string, contentHash: string, metadata: string): void;
+    /** Withdraw only an unsent error notice. Never claim it was delivered or touch a result row. */
+    withdrawErrorDelivery(id: number): void;
     private init;
     /**
      * Insert a message. Returns the auto-increment id, or -1 if duplicate.

package/dist/message-store.js

@@ -1,3 +1,4 @@
+import { errorIdentity } from "./terminal-errors.js";
 import Database from "better-sqlite3";
 import { resolve } from "path";
 import { mkdirSync } from "fs";
@@ -11,8 +12,101 @@ export class MessageStore {
         this.db.pragma("journal_mode = WAL");
         this.init();
     }
+    observeRunError(botName, chatId, provenance) {
+        const noticeId = errorIdentity(provenance.sessionKey, provenance.runId);
+        const previous = this.getErrorNotice(botName, chatId, noticeId);
+        if (previous) {
+            if (provenance.userStop) {
+                previous.provenance.userStop = true;
+                previous.status = "stopped";
+                previous.verdict = { state: "stopped", reason: "explicit_bridge_stop" };
+                this.saveErrorNotice(previous);
+            }
+            // A committed transcript abort is weaker than a gateway terminal error.
+            // One stronger envelope can wake a parked observation; repeats cannot.
+            const terminalChat = (p) => p.source === "chat" && (p.state === "error" || (p.state === "final" && p.stopReason === "error"));
+            if (!provenance.userStop && !previous.provenance.userStop && terminalChat(provenance) && !terminalChat(previous.provenance)
+                && ["pending", "parked"].includes(previous.status)) {
+                previous.provenance = provenance;
+                previous.status = "pending";
+                previous.checks = Math.min(previous.checks, 5);
+                previous.nextCheckAt = Date.now();
+                this.saveErrorNotice(previous);
+            }
+            return previous; // duplicate/late events never reset the budget
+        }
+        const record = { botName, chatId, noticeId, provenance, checks: 0,
+            nextCheckAt: Date.now(), createdAt: Date.now(), status: "pending" };
+        this.saveErrorNotice(record);
+        return record;
+    }
+    getErrorNotice(botName, chatId, noticeId) {
+        const row = this.db.prepare("SELECT record_json FROM error_notices WHERE bot_name=? AND chat_id=? AND notice_id=?")
+            .get(botName, chatId, noticeId);
+        return row ? JSON.parse(row.record_json) : undefined;
+    }
+    saveErrorNotice(record) {
+        this.db.prepare(`INSERT INTO error_notices (bot_name,chat_id,notice_id,record_json,next_check_at,status)
+      VALUES (?,?,?,?,?,?) ON CONFLICT(bot_name,chat_id,notice_id) DO UPDATE SET
+      record_json=excluded.record_json,next_check_at=excluded.next_check_at,status=excluded.status`)
+            .run(record.botName, record.chatId, record.noticeId, JSON.stringify(record), record.nextCheckAt, record.status);
+    }
+    listPendingErrorNotices(botName, chatId) {
+        return this.db.prepare("SELECT record_json FROM error_notices WHERE bot_name=? AND chat_id=? AND status='pending' ORDER BY next_check_at LIMIT 100")
+            .all(botName, chatId).map(row => JSON.parse(row.record_json));
+    }
+    /** A later exact final may be content-deduped against its own transcript.
+     * Upgrade only identical payloads with the same canonical session/run; never
+     * infer identity from text similarity or another run's successful answer. */
+    promoteExactRunFinal(botName, chatId, sessionKey, runId, contentHash, content, attachmentsJson) {
+        this.db.prepare(`UPDATE delivery_outbox
+      SET delivery_meta_json=json_set(delivery_meta_json,'$.provenance.final',json('true'))
+      WHERE bot_name=? AND chat_id=? AND source_type='assistant_visible' AND content_hash=?
+      AND content=? AND attachments_json=?
+      AND json_valid(delivery_meta_json)
+      AND json_extract(delivery_meta_json,'$.provenance.sessionKey')=?
+      AND json_extract(delivery_meta_json,'$.provenance.runId')=?`).run(botName, chatId, contentHash, content, attachmentsJson, sessionKey, runId);
+    }
+    hasExactRunFinalPayload(botName, chatId, p, content, attachmentsJson) {
+        return Boolean(this.db.prepare(`SELECT 1 FROM delivery_outbox
+      WHERE bot_name=? AND chat_id=? AND source_type='assistant_visible'
+      AND content=? AND attachments_json=? AND status IN ('pending','delivering','delivered')
+      AND json_valid(delivery_meta_json) AND json_extract(delivery_meta_json,'$.provenance.final')=1
+      AND json_extract(delivery_meta_json,'$.provenance.sessionKey')=?
+      AND json_extract(delivery_meta_json,'$.provenance.runId')=? LIMIT 1`)
+            .get(botName, chatId, content, attachmentsJson, p.sessionKey, p.runId));
+    }
+    hasRunFinalDelivery(botName, chatId, p, confirmed) {
+        return Boolean(p.runId && this.db.prepare(`SELECT 1 FROM delivery_outbox
+      WHERE bot_name=? AND chat_id=? AND source_type='assistant_visible'
+      AND json_valid(delivery_meta_json)
+      AND json_extract(delivery_meta_json,'$.provenance.final')=1
+      AND json_extract(delivery_meta_json,'$.provenance.sessionKey')=?
+      AND json_extract(delivery_meta_json,'$.provenance.runId')=?
+      AND ${confirmed ? "status='delivered'" : "status IN ('pending','delivering')"} LIMIT 1`)
+            .get(botName, chatId, p.sessionKey, p.runId));
+    }
+    renewUnsentErrorDelivery(id, content, contentHash, metadata) {
+        this.db.prepare(`UPDATE delivery_outbox SET status='pending',content=?,content_hash=?,delivery_meta_json=?,updated_at=?
+      WHERE id=? AND source_type='run_error' AND status='failed' AND text_delivered=0`)
+            .run(content, contentHash, metadata, Date.now(), id);
+    }
+    /** Withdraw only an unsent error notice. Never claim it was delivered or touch a result row. */
+    withdrawErrorDelivery(id) {
+        // claimDelivery reserves a send attempt before the asynchronous evidence
+        // guard. Withdrawing here means no platform send was attempted: refund only
+        // that current claim, never an earlier failed/ambiguous platform attempt.
+        this.db.prepare("UPDATE delivery_outbox SET status='failed', attempts=MAX(0,attempts-1), updated_at=? WHERE id=? AND source_type='run_error' AND status='delivering' AND text_delivered=0")
+            .run(Date.now(), id);
+    }
     init() {
         this.db.exec(`
+      CREATE TABLE IF NOT EXISTS error_notices (
+        bot_name TEXT NOT NULL, chat_id TEXT NOT NULL, notice_id TEXT NOT NULL,
+        record_json TEXT NOT NULL, next_check_at INTEGER NOT NULL,
+        status TEXT NOT NULL, PRIMARY KEY(bot_name, chat_id, notice_id)
+      );
+      CREATE INDEX IF NOT EXISTS idx_error_notices_due ON error_notices(bot_name, chat_id, status, next_check_at);
       CREATE TABLE IF NOT EXISTS messages (
         id INTEGER PRIMARY KEY AUTOINCREMENT,
         chat_id TEXT NOT NULL,

package/dist/openclaw-client.d.ts

@@ -1,3 +1,4 @@
+import { type ErrorProvenance, type ProactiveMessageMeta } from "./terminal-errors.js";
 import { SessionWaitPaused, type SessionRuntimeStatus } from "./session-status.js";
 import { OpenClawConfig } from "./config.js";
 import { ChatMessage } from "./message-store.js";
@@ -76,6 +77,11 @@ export declare class OpenClawClient {
     private mutedProactiveSessionCounts;
     /** Sessions force-aborted by /stop; collectReply should finish immediately instead of waiting for idle timeout. */
     private forceAbortedSessions;
+    /** Explicit-stop evidence comes from exact authorized abort response run IDs,
+     * never the persistent session flag used by the original collector. */
+    private explicitlyStoppedRuns;
+    private pendingExplicitStops;
+    private isExplicitlyStoppedRun;
     /** Global limiter for chat.send RPC calls; large multi-bot fan-out can
      * saturate the Gateway before collectReply even starts. The slot is released
      * as soon as the chat.send RPC returns a runId; collectReply does not hold it.
@@ -137,6 +143,14 @@ export declare class OpenClawClient {
         model?: string;
         label?: string;
     }): Promise<any>;
+    /** True when an RPC error is the Gateway's "session is archived" refusal. */
+    isArchivedSessionError(err: unknown): boolean;
+    /**
+     * Restore an archived session (e.g. auto-archived by the Gateway's
+     * active-session-cap) so new work can start. sessions.patch requires
+     * expectedSessionId, so describe first, then patch archived=false.
+     */
+    unarchiveSession(key: string): Promise<boolean>;
     getSessionStatus(key: string): Promise<any>;
     injectAssistantMessage(params: {
         sessionKey: string;
@@ -208,6 +222,7 @@ export declare class OpenClawClient {
     abortChat(sessionKey: string, runId?: string): Promise<any>;
     private sessionKeyVariants;
     private trackChatEventSession;
+    inspectRunError(provenance: ErrorProvenance): Promise<import("./terminal-errors.js").ErrorVerdict>;
     private extractTextFromChatMessage;
     private emitProactiveForSession;
     private suppressSessionKeys;
@@ -279,10 +294,7 @@ export declare class OpenClawClient {
      * Subscribe to message events for a session.
      * When the agent proactively produces a message, the callback fires.
      */
-    subscribeSession(sessionKey: string, onMessage: (text: string, meta?: {
-        sourceType?: string;
-        runId?: string;
-    }) => void): Promise<void>;
+    subscribeSession(sessionKey: string, onMessage: (text: string, meta?: ProactiveMessageMeta) => void): Promise<void>;
     setVerboseTranscriptDelivery(sessionKey: string, enabled: boolean): void;
     unsubscribeSession(sessionKey: string): Promise<void>;
     /**

package/dist/openclaw-client.js

@@ -1,4 +1,5 @@
 import WebSocket from "ws";
+import { inspectError, genericFailure } from "./terminal-errors.js";
 import { SessionWaitPaused, normalizeSessionRuntimeStatus, isWaitTimeout, FOREGROUND_WAIT_MS } from "./session-status.js";
 import { createHash, randomUUID } from "crypto";
 import { mkdirSync, readFileSync, statSync, writeFileSync } from "fs";
@@ -80,6 +81,23 @@ export class OpenClawClient {
     mutedProactiveSessionCounts = new Map();
     /** Sessions force-aborted by /stop; collectReply should finish immediately instead of waiting for idle timeout. */
     forceAbortedSessions = new Set();
+    /** Explicit-stop evidence comes from exact authorized abort response run IDs,
+     * never the persistent session flag used by the original collector. */
+    explicitlyStoppedRuns = new Map();
+    pendingExplicitStops = new Map();
+    isExplicitlyStoppedRun(sessionKey, runId) {
+        if (!runId)
+            return false;
+        const key = JSON.stringify([this.canonicalSessionKey(sessionKey), runId]);
+        const at = this.explicitlyStoppedRuns.get(key);
+        if (at === undefined)
+            return false;
+        if (Date.now() - at > 24 * 60 * 60_000) {
+            this.explicitlyStoppedRuns.delete(key);
+            return false;
+        }
+        return true;
+    }
     /** Global limiter for chat.send RPC calls; large multi-bot fan-out can
      * saturate the Gateway before collectReply even starts. The slot is released
      * as soon as the chat.send RPC returns a runId; collectReply does not hold it.
@@ -639,6 +657,18 @@ export class OpenClawClient {
         // structured content arrays rather than a plain string. Extract only visible
         // text parts and ignore thinking/tool blocks so the bridge can deliver final
         // cron results via the bot.
+        if (msg?.role === "assistant" && ["error", "aborted"].includes(msg?.stopReason)) {
+            if (this.mutedProactiveSessions.has(rawKey) || this.mutedProactiveSessions.has(shortKey))
+                return false;
+            if (runId && this.ownedDeliveryRuns.has(runId))
+                return false;
+            return this.emitProactiveForSession(rawKey, String(msg.errorMessage || "Agent run failed"), {
+                sourceType: "run_error", runId,
+                error: { sessionKey: this.canonicalSessionKey(rawKey), runId: runId || "", source: "session.message",
+                    state: "final", stopReason: msg.stopReason, detail: String(msg.errorMessage || ""),
+                    ...(this.isExplicitlyStoppedRun(rawKey, runId) ? { userStop: true } : {}) },
+            });
+        }
         const allowVerboseTranscript = this.isVerboseTranscriptEnabled(rawKey);
         const proactiveText = this.extractVisibleAssistantText(msg, { allowMixedToolText: allowVerboseTranscript });
         if (!proactiveText)
@@ -658,7 +688,8 @@ export class OpenClawClient {
         const cb = this.sessionMessageCallbacks.get(rawKey) || this.sessionMessageCallbacks.get(shortKey);
         if (cb) {
             if (runId)
-                cb(proactiveText, { runId });
+                cb(proactiveText, { runId, sessionKey: this.canonicalSessionKey(rawKey), final: msg?.stopReason === "stop",
+                    ...(!msg?.stopReason && genericFailure(proactiveText) ? { genericErrorCandidate: true } : {}) });
             else
                 cb(proactiveText);
         }
@@ -1514,6 +1545,34 @@ export class OpenClawClient {
     async patchSession(params) {
         return this.rpc("sessions.patch", { ...params, key: this.canonicalSessionKey(params.key) }, 10000);
     }
+    /** True when an RPC error is the Gateway's "session is archived" refusal. */
+    isArchivedSessionError(err) {
+        const msg = err instanceof Error ? err.message : String(err ?? "");
+        return /is archived[.,]|Restore it before starting new work/i.test(msg);
+    }
+    /**
+     * Restore an archived session (e.g. auto-archived by the Gateway's
+     * active-session-cap) so new work can start. sessions.patch requires
+     * expectedSessionId, so describe first, then patch archived=false.
+     */
+    async unarchiveSession(key) {
+        const canonical = this.canonicalSessionKey(key);
+        try {
+            const info = await this.rpc("sessions.describe", { key: canonical }, 15000);
+            const sessionId = info?.session?.sessionId;
+            if (!sessionId)
+                return false;
+            if (info?.session?.archived !== true)
+                return true; // already active
+            const res = await this.rpc("sessions.patch", { key: canonical, expectedSessionId: sessionId, archived: false }, 15000);
+            console.log(`[OpenClaw] unarchived session ${key}: ${res?.ok === true ? "ok" : "unexpected response"}`);
+            return res?.ok === true;
+        }
+        catch (err) {
+            console.warn(`[OpenClaw] unarchive failed for ${key}:`, err instanceof Error ? err.message : err);
+            return false;
+        }
+    }
     async getSessionStatus(key) {
         return this.rpc("sessions.describe", { key: this.canonicalSessionKey(key) });
     }
@@ -1770,8 +1829,20 @@ export class OpenClawClient {
         const maxLines = Number.isFinite(options.maxLines)
             ? Math.max(1, Math.floor(options.maxLines))
             : undefined;
+        const sendCompact = () => this.rpc("sessions.compact", { key: this.canonicalSessionKey(key), ...(maxLines !== undefined ? { maxLines } : {}) }, 10 * 60 * 1000);
         try {
-            return await this.rpc("sessions.compact", { key: this.canonicalSessionKey(key), ...(maxLines !== undefined ? { maxLines } : {}) }, 10 * 60 * 1000);
+            try {
+                return await sendCompact();
+            }
+            catch (err) {
+                if (!this.isArchivedSessionError(err))
+                    throw err;
+                console.warn(`[OpenClaw] sessions.compact hit archived session for ${key}; restoring and retrying once`);
+                const restored = await this.unarchiveSession(key);
+                if (!restored)
+                    throw err;
+                return await sendCompact();
+            }
         }
         finally {
             const mode = maxLines === undefined ? "semantic" : `maxLines=${maxLines}`;
@@ -1789,13 +1860,39 @@ 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) {
+            for (const [identity, at] of this.explicitlyStoppedRuns)
+                if (Date.now() - at > 24 * 60 * 60_000)
+                    this.explicitlyStoppedRuns.delete(identity);
             // Mark the session so any in-flight collectReply finishes immediately
             // instead of treating the cancelled lifecycle as a transient state.
-            this.forceAbortedSessions.add(key);
-            this.forceAbortedSessions.add(this.shortKey(key));
+            if (this.runStateChecks.has(key)) {
+                this.forceAbortedSessions.add(key);
+                this.forceAbortedSessions.add(this.shortKey(key));
+            }
         }
         const params = runId ? { sessionKey: key, runId } : { sessionKey: key };
-        return this.rpc("chat.abort", params, 5000).catch(() => { });
+        if (runId)
+            return this.rpc("chat.abort", params, 5000).catch(() => { });
+        let resolveStop;
+        const barrier = new Promise(resolve => { resolveStop = resolve; });
+        this.pendingExplicitStops.set(key, barrier);
+        try {
+            const result = await this.rpc("chat.abort", params, 5000).catch(() => undefined);
+            // The authorized abort response names the exact runs actually stopped;
+            // it also covers queued/unseen runs with no local status/delta event.
+            if (result?.aborted === true && Array.isArray(result.runIds)) {
+                for (const stopped of result.runIds)
+                    if (typeof stopped === "string" && stopped) {
+                        this.explicitlyStoppedRuns.set(JSON.stringify([key, stopped]), Date.now());
+                    }
+            }
+            return result;
+        }
+        finally {
+            resolveStop();
+            if (this.pendingExplicitStops.get(key) === barrier)
+                this.pendingExplicitStops.delete(key);
+        }
     }
     sessionKeyVariants(key) {
         const shortKey = this.shortKey(key);
@@ -1812,39 +1909,55 @@ export class OpenClawClient {
             // still reach the proactive callback.
             return;
         }
-        // External WebChat/Control UI (including a steer admission that became a
-        // separate run): hide streaming mirrors, then emit its final exactly once.
-        if (state === "delta") {
+        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";
+        if (isError) {
+            const detail = String(payload?.errorMessage || payload?.message?.errorMessage || payload?.error || payload?.reason || "").trim();
+            const aborted = state === "aborted" || stopReason === "aborted";
+            const text = `⚠️ Agent run ${aborted ? "was aborted" : "failed"}${detail ? `: ${detail}` : ""}`;
+            this.emitProactiveForSession(sessionKey, text, {
+                sourceType: "run_error", runId,
+                error: { sessionKey: this.canonicalSessionKey(sessionKey), runId, source: "chat", state: state || "final",
+                    ...(typeof stopReason === "string" ? { stopReason } : {}), detail,
+                    ...(this.isExplicitlyStoppedRun(sessionKey, runId) ? { userStop: true } : {}) },
+            });
+            this.releaseSuppressedSessionKeysAfter(keys, 0);
+        }
+        else if (state === "delta") {
             this.suppressSessionKeys(keys);
         }
         else if (state === "final") {
             const text = this.extractTextFromChatMessage(payload?.message);
             if (text)
-                this.emitProactiveForSession(sessionKey, text, runId);
+                this.emitProactiveForSession(sessionKey, text, {
+                    runId, sessionKey: this.canonicalSessionKey(sessionKey), final: payload?.yielded !== true,
+                    ...(!stopReason && genericFailure(text) ? { genericErrorCandidate: true } : {}),
+                });
             this.releaseSuppressedSessionKeysAfter(keys, 30000);
         }
-        else if (state === "error" || state === "aborted") {
-            const detail = String(payload?.errorMessage || payload?.error || payload?.reason || "").trim();
-            const text = state === "error"
-                ? `⚠️ Agent run failed${detail ? `: ${detail}` : ""}`
-                : `⚠️ Agent run was aborted${detail ? `: ${detail}` : ""}`;
-            this.emitProactiveForSession(sessionKey, text, runId, "run_error");
-            this.releaseSuppressedSessionKeysAfter(keys, 0);
+    }
+    async inspectRunError(provenance) {
+        await this.pendingExplicitStops.get(this.canonicalSessionKey(provenance.sessionKey));
+        if (this.isExplicitlyStoppedRun(provenance.sessionKey, provenance.runId)) {
+            return { state: "stopped", reason: "exact_run_abort_receipt" };
         }
+        const verdict = await inspectError(provenance, (method, params, timeout) => this.rpc(method, params, timeout));
+        // A stop request can begin while task/wait evidence is in flight.
+        await this.pendingExplicitStops.get(this.canonicalSessionKey(provenance.sessionKey));
+        return this.isExplicitlyStoppedRun(provenance.sessionKey, provenance.runId)
+            ? { state: "stopped", reason: "exact_run_abort_receipt" } : verdict;
     }
     extractTextFromChatMessage(message) {
         const parts = Array.isArray(message?.content) ? message.content : [];
         return parts.filter((part) => part?.type === "text" && typeof part.text === "string").map((part) => part.text).join("\n").trim();
     }
-    emitProactiveForSession(sessionKey, text, runId, sourceType) {
+    emitProactiveForSession(sessionKey, text, meta) {
         const [shortKey, fullKey] = this.sessionKeyVariants(sessionKey);
         const cb = this.sessionMessageCallbacks.get(fullKey) || this.sessionMessageCallbacks.get(shortKey);
         if (!cb)
             return false;
-        if (runId || sourceType)
-            cb(text, { ...(runId ? { runId } : {}), ...(sourceType ? { sourceType } : {}) });
-        else
-            cb(text);
+        cb(text, meta);
         return true;
     }
     suppressSessionKeys(keys) {
@@ -1979,13 +2092,28 @@ export class OpenClawClient {
             const sendStartedAt = Date.now();
             try {
                 await params.onSendAttempt?.();
-                result = await this.rpc("chat.send", {
+                const sendChat = () => this.rpc("chat.send", {
                     sessionKey: this.canonicalSessionKey(sk),
                     message: params.message,
                     attachments: params.attachments,
                     deliver: params.deliver ?? false,
                     idempotencyKey: randomUUID(),
                 });
+                try {
+                    result = await sendChat();
+                }
+                catch (err) {
+                    // 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;
+                    console.warn(`[OpenClaw] chat.send hit archived session for ${sk}; restoring and retrying once`);
+                    const restored = await this.unarchiveSession(sk);
+                    if (!restored)
+                        throw err;
+                    result = await sendChat();
+                }
             }
             finally {
                 releaseChatSendSlot();
@@ -2221,6 +2349,7 @@ export class OpenClawClient {
         this.pendingSteerTexts.clear();
         this.steerConsumedCallbacks.clear();
         this.ownedDeliveryRuns.clear();
+        this.explicitlyStoppedRuns.clear();
         if (this.ws) {
             this.ws.close();
             this.ws = null;

package/dist/terminal-errors.d.ts

@@ -0,0 +1,49 @@
+/** Only gateway envelopes / committed assistant metadata populate this record. */
+export interface ErrorProvenance {
+    sessionKey: string;
+    runId: string;
+    source: "chat" | "session.message";
+    state: string;
+    stopReason?: string;
+    detail?: string;
+    userStop?: boolean;
+}
+export interface ProactiveMessageMeta {
+    sourceType?: string;
+    runId?: string;
+    sessionKey?: string;
+    final?: boolean;
+    error?: ErrorProvenance;
+    terminalEvidence?: ErrorVerdict;
+    /** Missing stopReason: only a persisted error for this exact run may qualify. */
+    genericErrorCandidate?: boolean;
+}
+export interface TaskEvidence {
+    id: string;
+    kind?: string;
+    runId?: string;
+    sourceId?: string;
+    sessionKey?: string;
+    ownerKey?: string;
+    childSessionKey?: string;
+    parentTaskId?: string;
+    status: string;
+    deliveryStatus?: string;
+    terminalOutcome?: string;
+}
+export interface ErrorVerdict {
+    state: "pending" | "suppressed" | "terminal" | "stopped";
+    reason: string;
+    task?: TaskEvidence;
+    terminalKey?: string;
+    text?: string;
+}
+export type ReadRPC = (method: string, params: Record<string, unknown>, timeoutMs: number) => Promise<any>;
+export declare const errorIdentity: (sessionKey: string, runId: string) => string;
+export declare const genericFailure: (text: string) => boolean;
+export declare function announceCandidate(p: ErrorProvenance): {
+    runId: string;
+    childSessionKey?: string;
+} | undefined;
+/** Read-only and bounded: no model invocation, replay, cancellation or session-status heuristic. */
+export declare function inspectError(p: ErrorProvenance, rpc: ReadRPC): Promise<ErrorVerdict>;

package/dist/terminal-errors.js

@@ -0,0 +1,116 @@
+import { createHash } from "node:crypto";
+export const errorIdentity = (sessionKey, runId) => createHash("sha256").update(JSON.stringify([sessionKey, runId])).digest("hex");
+export const genericFailure = (text) => text.trim() === "The agent run failed before producing a reply.";
+// These are candidate locators, NOT business identities. Verify every component
+// against tasks.list + a fresh tasks.get. Unsupported/batch forms stay unknown.
+export function announceCandidate(p) {
+    const uuid = "[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}";
+    const direct = p.runId.match(new RegExp(`^announce:v1:(agent:[^:]+:.+):(${uuid})$`));
+    if (direct)
+        return { childSessionKey: direct[1], runId: direct[2] };
+    const agent = p.sessionKey.match(/^agent:([^:]+):/)?.[1];
+    const prefix = `announce:requester-settle:${agent}:${p.sessionKey}:`;
+    if (!agent || !p.runId.startsWith(prefix))
+        return;
+    const wake = p.runId.slice(prefix.length).match(new RegExp(`^(${uuid})(?::yield-\\d+)?(?::retry-\\d+)?$`));
+    if (wake)
+        return { runId: wake[1] };
+}
+function projectTask(t) {
+    const out = {};
+    for (const k of ["id", "kind", "runId", "sourceId", "sessionKey", "ownerKey", "childSessionKey", "parentTaskId", "status", "deliveryStatus", "terminalOutcome"]) {
+        if (typeof t?.[k] === "string")
+            out[k] = t[k];
+    }
+    return out;
+}
+function matches(t, p, c) {
+    return Boolean(t.id && t.kind === "subagent" && t.runId === c.runId
+        && t.sessionKey === p.sessionKey && t.ownerKey === p.sessionKey
+        && t.childSessionKey && (!c.childSessionKey || t.childSessionKey === c.childSessionKey));
+}
+/** Read-only and bounded: no model invocation, replay, cancellation or session-status heuristic. */
+export async function inspectError(p, rpc) {
+    if (p.userStop)
+        return { state: "stopped", reason: "explicit_bridge_stop" };
+    const pending = (reason, task) => ({ state: "pending", reason, task });
+    const announce = p.runId.startsWith("announce:");
+    if (!p.runId)
+        return pending("missing_run_identity");
+    if (!announce) {
+        // Ordinary chat.error is a gateway terminal envelope (after gateway retry
+        // grace). Do not rewrite normal collector/auth/parameter/tool-error handling.
+        if (p.source === "chat" && (p.state === "error" || (p.state === "final" && p.stopReason === "error")))
+            return {
+                state: "terminal", reason: "ordinary_gateway_error", terminalKey: `run-error:${errorIdentity(p.sessionKey, p.runId)}`,
+                text: `⚠️ Agent run failed${p.detail ? `: ${p.detail}` : ""}`,
+            };
+        try {
+            const wait = await rpc("agent.wait", { runId: p.runId, timeoutMs: 1 }, 2000);
+            const ended = wait?.endedAt;
+            const started = wait?.startedAt;
+            const terminalTime = typeof ended === "number" && Number.isFinite(ended) && ended > 0
+                && (started === undefined || (typeof started === "number" && Number.isFinite(started) && started >= 0 && ended >= started));
+            if (wait?.runId === p.runId && wait?.status === "error" && wait?.pendingError !== true
+                && wait?.yielded !== true && terminalTime)
+                return {
+                    state: "terminal", reason: "exact_run_terminal_error", terminalKey: `run-error:${errorIdentity(p.sessionKey, p.runId)}`,
+                    text: "⚠️ 该次运行已终止，未能完成回复。",
+                };
+            return pending("wait_not_terminal_failure");
+        }
+        catch {
+            return pending("wait_unavailable");
+        }
+    }
+    const candidate = announceCandidate(p);
+    if (!candidate)
+        return pending("unsupported_announce_lineage");
+    try {
+        // At most two pages; absence or truncation is never evidence of failure.
+        let cursor;
+        const matchesFound = [];
+        for (let page = 0; page < 2; page++) {
+            const result = await rpc("tasks.list", { sessionKey: p.sessionKey, limit: 100, ...(cursor ? { cursor } : {}) }, 2000);
+            if (!Array.isArray(result?.tasks))
+                return pending("unsupported_task_response");
+            for (const raw of result.tasks) {
+                const task = projectTask(raw);
+                if (matches(task, p, candidate))
+                    matchesFound.push(task);
+            }
+            cursor = typeof result.nextCursor === "string" ? result.nextCursor : undefined;
+            if (!cursor)
+                break;
+        }
+        const ids = [...new Set(matchesFound.map(t => t.id))];
+        if (ids.length !== 1 || cursor)
+            return pending("task_lineage_missing_ambiguous_or_truncated");
+        const task = projectTask((await rpc("tasks.get", { taskId: ids[0] }, 2000))?.task);
+        if (task.id !== ids[0] || !matches(task, p, candidate))
+            return pending("task_lineage_changed");
+        if (["queued", "running"].includes(task.status) || ["pending", "session_queued"].includes(task.deliveryStatus || "")) {
+            return pending("matching_task_or_delivery_continuing", task);
+        }
+        if (task.status === "completed" && task.deliveryStatus === "delivered" && task.terminalOutcome !== "blocked") {
+            return { state: "suppressed", reason: "matching_task_completed_delivery_confirmed", task };
+        }
+        const terminalKey = `task-error:${errorIdentity(p.sessionKey, task.id)}`;
+        // A failed child is not the whole user request. Do not borrow another child's
+        // successful result, or substitute raw child output for the parent answer.
+        if (["failed", "timed_out"].includes(task.status) && ["delivered", "failed", "not_applicable"].includes(task.deliveryStatus || "")) {
+            return { state: "terminal", reason: "matching_child_terminal_failure", task, terminalKey,
+                text: `⚠️ 子任务 ${task.id} ${task.status === "timed_out" ? "已超时终止" : "已失败"}；这不代表同会话其他任务失败。` };
+        }
+        // Public schema has no requester-settle retry counter. Only the explicit
+        // blocked + failed delivery projection proves that continuation is blocked.
+        if (task.status === "completed" && task.deliveryStatus === "failed" && task.terminalOutcome === "blocked") {
+            return { state: "terminal", reason: "matching_completion_delivery_blocked", task, terminalKey,
+                text: `⚠️ 子任务 ${task.id} 已完成，但结果回传已终止，需要人工处理；并非任务执行失败。` };
+        }
+        return pending("task_does_not_prove_attempt_chain_terminal", task);
+    }
+    catch {
+        return pending("task_lookup_unavailable");
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-lark-multi-agent",
-  "version": "1.4.12",
+  "version": "1.5.0",
   "description": "Multi-bot Lark/Feishu bridge for OpenClaw, with per-bot model routing and isolated sessions",
   "type": "module",
   "scripts": {