larkway 0.3.15 → 0.3.17

package/README.md

@@ -8,7 +8,7 @@
 
 You @ the bot in a Feishu thread. It runs on your machine — reading your real codebase, executing commands, opening MRs — and posts the result back. You define what the agent knows and what it can do. Larkway just carries the messages.
 
-**Current release: v0.3.15**
+**Current release: v0.3.17**
 
 ---
 

package/README.zh.md

@@ -8,7 +8,7 @@
 
 你在飞书话题里 @ bot，它在你的机器上运行——读真实代码库、执行命令、开 MR——把结果贴回飞书。你定义 agent 知道什么、能做什么。Larkway 只负责传递消息。
 
-**当前版本：v0.3.15**
+**当前版本：v0.3.17**
 
 ---
 

package/dist/cli/index.js

@@ -112093,7 +112093,7 @@ function channelMsgToLarkEvent(msg) {
     create_time: m?.["create_time"] ?? String(msg.createTime ?? Date.now())
   };
 }
-var import_node_sdk, execFile4, LEARNED_CHATS_LIMIT, SEEN_MESSAGES_LIMIT, MAX_MESSAGE_ATTEMPTS, OPEN_CHAT_DISCOVERY_LOOKBACK_MS, OPEN_CHAT_DISCOVERY_BOOTSTRAP_LOOKBACK_MS, PROCESSING_REACTION_EMOJI, DEFAULT_CONNECT_GRACE_MS, ChannelClient;
+var import_node_sdk, execFile4, LEARNED_CHATS_LIMIT, SEEN_MESSAGES_LIMIT, MAX_MESSAGE_ATTEMPTS, OPEN_CHAT_DISCOVERY_LOOKBACK_MS, OPEN_CHAT_DISCOVERY_BOOTSTRAP_LOOKBACK_MS, PROCESSING_REACTION_EMOJI, GAP_FILL_MAX_ATTEMPTS, GAP_FILL_BACKOFF_BASE_MS, UNRESOLVED_WINDOW_MAX_CHATS, UNRESOLVED_WINDOW_MAX_AGE_MS, DEFAULT_CONNECT_GRACE_MS, ChannelClient;
 var init_channelClient = __esm({
   "src/lark/channelClient.ts"() {
     "use strict";
@@ -112107,6 +112107,10 @@ var init_channelClient = __esm({
     OPEN_CHAT_DISCOVERY_LOOKBACK_MS = 9e4;
     OPEN_CHAT_DISCOVERY_BOOTSTRAP_LOOKBACK_MS = 30 * 60 * 1e3;
     PROCESSING_REACTION_EMOJI = "Typing";
+    GAP_FILL_MAX_ATTEMPTS = 3;
+    GAP_FILL_BACKOFF_BASE_MS = 1e3;
+    UNRESOLVED_WINDOW_MAX_CHATS = 50;
+    UNRESOLVED_WINDOW_MAX_AGE_MS = 30 * 60 * 1e3;
     DEFAULT_CONNECT_GRACE_MS = 3e3;
     ChannelClient = class {
       opts;
@@ -112171,6 +112175,27 @@ var init_channelClient = __esm({
        * search space.
        */
       recentlySeenChatIds = /* @__PURE__ */ new Set();
+      /**
+       * PER-CHAT unresolved gapFill windows: chatId → the OLDEST windowStart (ms) for
+       * which that chat's lark-cli history pull still failed after all retries. On a
+       * later gapFill that ACTUALLY pulls this chat, we extend the look-back to cover
+       * its oldest unresolved windowStart and only clear it once the pull truly
+       * reached back that far (its `--start` <= the tracked windowStart). Per-chat (not
+       * a single shared list) so a successful run over chat-set {B} can never falsely
+       * resolve chat A's window (BLOCKER 1), and the look-back-vs-clamp mismatch can
+       * never mark a window resolved before it was reached (BLOCKER 2).
+       *
+       * Bounded: one timestamp per chat (so naturally bounded by #chats), pruned by age
+       * (UNRESOLVED_WINDOW_MAX_AGE_MS — older = unrecoverable from history anyway) and
+       * capped at UNRESOLVED_WINDOW_MAX_CHATS tracked chats.
+       */
+      unresolvedGapWindowByChat = /* @__PURE__ */ new Map();
+      /**
+       * Backoff sleep used by the per-chat history-pull retry. Indirected through a
+       * field purely so tests can observe/await the backoff deterministically; in
+       * production it is the real timer-based {@link sleep}.
+       */
+      gapFillSleep = sleep;
       openChatDiscoveryTimer = null;
       openChatDiscoveryRunning = false;
       openChatDiscoveryBootstrapped = false;
@@ -112192,6 +112217,28 @@ var init_channelClient = __esm({
         }
         this.opts = opts;
       }
+      /**
+       * TEST SEAM (deletable): override the gap-fill retry backoff sleep so unit
+       * tests can observe the backoff durations and avoid real timers. No-op for
+       * production — the default is the real {@link sleep}. Returns the recorded
+       * backoff arg via the provided callback's own bookkeeping.
+       */
+      setGapFillSleepForTest(fn) {
+        this.gapFillSleep = fn;
+      }
+      /** TEST-ONLY read of the per-chat unresolved-window replay map (chatId → windowStart). */
+      unresolvedGapWindowsForTest() {
+        return new Map(this.unresolvedGapWindowByChat);
+      }
+      /**
+       * TEST-ONLY direct gapFill invocation with an explicit chat-set override —
+       * mirrors exactly how open-chat discovery calls gapFill on a SUBSET of chats.
+       * Used to reproduce the cross-chat-set replay isolation (BLOCKER 1) without
+       * standing up the full discovery timer.
+       */
+      async gapFillForTest(disconnectAt, chatIds) {
+        await this.gapFill(disconnectAt, (s) => console.log(`[channel.client] ${s}`), chatIds);
+      }
       /**
        * Async iterator over inbound events — interface-compatible with LarkClient.
        * Connects the WS on first call. The SDK's policy gate (requireMention +
@@ -112257,7 +112304,25 @@ var init_channelClient = __esm({
           // ── WS robustness knobs (node-sdk ≥1.64; all OFF by default) ──────────
           // Abort a handshake that hangs on a stuck DNS/proxy/NAT path so the retry
           // loop can try again, instead of waiting indefinitely. Successful TLS
-          // handshakes are tens of ms; 15s is a wide safety margin.
+          // handshakes are tens of ms; 15s is a wide safety margin. KEPT ON: it is
+          // the right behaviour (abort + reconnect beats hanging forever).
+          //
+          // CAVEAT — raw '_WebSocket' 'error' on abort: when this timeout fires the
+          // SDK aborts the underlying ws, which emits a RAW 'error' event on the
+          // socket. That socket is owned privately inside node-sdk's WSClient
+          // (no public `on()`, no accessor for the raw ws — verified against
+          // node-sdk 1.67.0 types: WSClient is not an EventEmitter and keeps the
+          // `_WebSocket` in a closure), so we CANNOT attach a precise 'error'
+          // listener here. With no listener, Node re-throws it as an
+          // uncaughtException → it would kill the whole (multi-bot) process.
+          //   → That raw error is instead caught by the process-level crash guard
+          //     in main.ts (registerCrashGuard: uncaughtException handler that logs
+          //     and never exits). The channel-level `channel.on("error", …)` below
+          //     is a DIFFERENT, higher-level error and does NOT cover this raw case.
+          //   → Residual uncertainty (left for acceptance load-testing): that the
+          //     process guard reliably catches this specific raw abort path under
+          //     real network flap. If a future node-sdk / @larksuite/channel exposes
+          //     the ws or attaches its own listener, prefer that and drop the guard.
           handshakeTimeoutMs: 15e3,
           // Liveness watchdog (SECONDS): if no inbound frame arrives within this
           // window after the last ping, treat the socket as dead and reconnect —
@@ -112374,9 +112439,6 @@ var init_channelClient = __esm({
         const MAX_GAP_FILL_WINDOW_MS = 5 * 60 * 1e3;
         const BUFFER_MS = 3e4;
         const now = Date.now();
-        const windowStart = Math.max(disconnectAt - BUFFER_MS, now - MAX_GAP_FILL_WINDOW_MS);
-        const startIso = new Date(windowStart).toISOString();
-        const endIso = new Date(now + BUFFER_MS).toISOString();
         const larkCli = this.opts.larkCliPath ?? "lark-cli";
         const profileArgs = this.opts.larkCliProfile ? ["--profile", this.opts.larkCliProfile] : [];
         const botOpenId = this.opts.botOpenId;
@@ -112386,16 +112448,29 @@ var init_channelClient = __esm({
           ...this.opts.allowedChatIds,
           ...this.recentlySeenChatIds
         ]);
+        this.pruneUnresolvedGapWindows(now);
+        let oldestRelevantUnresolved = Infinity;
+        for (const chatId of gapFillChatIds) {
+          const ws = this.unresolvedGapWindowByChat.get(chatId);
+          if (ws !== void 0 && ws < oldestRelevantUnresolved) oldestRelevantUnresolved = ws;
+        }
+        const hasReplay = oldestRelevantUnresolved !== Infinity;
+        const lookBackFrom = Math.min(disconnectAt, hasReplay ? oldestRelevantUnresolved : disconnectAt);
+        const clampCeilingMs = hasReplay ? UNRESOLVED_WINDOW_MAX_AGE_MS : MAX_GAP_FILL_WINDOW_MS;
+        const windowStart = Math.max(lookBackFrom - BUFFER_MS, now - clampCeilingMs);
+        const startIso = new Date(windowStart).toISOString();
+        const endIso = new Date(now + BUFFER_MS).toISOString();
         if (gapFillChatIds.size === 0) {
           log(
             `gap-fill skipped: no known chats for window=${startIso}..${endIso} (allowedChatIds is empty and no live chat has been seen yet)`
           );
           return;
         }
+        let anyChatFailed = false;
         for (const chatId of gapFillChatIds) {
           if (this.closed) break;
           try {
-            const { stdout: stdout2 } = await execFile4(larkCli, [
+            const args = [
               "im",
               "+chat-messages-list",
               "--as",
@@ -112414,7 +112489,8 @@ var init_channelClient = __esm({
               "json",
               "--no-reactions",
               ...profileArgs
-            ]);
+            ];
+            const { stdout: stdout2 } = await this.execWithRetry(larkCli, args, chatId, log);
             let messages;
             try {
               messages = parseLarkCliMessages(stdout2) ?? [];
@@ -112482,16 +112558,91 @@ var init_channelClient = __esm({
               this.queue.push(ev);
               totalDispatched++;
             }
+            this.resolveUnresolvedGapWindow(chatId, windowStart);
           } catch (e) {
+            anyChatFailed = true;
+            this.recordUnresolvedGapWindow(chatId, windowStart, log);
             log(
-              `gap-fill: lark-cli failed for chat ${chatId}: ` + (e instanceof Error ? e.message : String(e))
+              `gap-fill: lark-cli failed for chat ${chatId} after ${GAP_FILL_MAX_ATTEMPTS} attempt(s): ` + (e instanceof Error ? e.message : String(e))
             );
           }
         }
         log(
-          `gap-fill complete: window=${startIso}..${endIso}, fetched=${totalFetched}, dispatched=${totalDispatched}`
+          `gap-fill complete: window=${startIso}..${endIso}, fetched=${totalFetched}, dispatched=${totalDispatched}` + (anyChatFailed ? ` (some chats failed \u2014 per-chat windows queued for replay)` : ``)
         );
       }
+      /**
+       * Run a lark-cli history pull with bounded retries + exponential backoff.
+       * Retries on ANY thrown error (transient TLS timeout being the motivating case),
+       * up to {@link GAP_FILL_MAX_ATTEMPTS}. Backoff is GAP_FILL_BACKOFF_BASE_MS *
+       * 2^(attempt-1) (~1s / 2s). Re-throws the last error if all attempts fail so the
+       * caller can flag the window for replay. Backoff goes through {@link gapFillSleep}
+       * (injectable) so tests can observe it deterministically.
+       */
+      async execWithRetry(larkCli, args, chatId, log) {
+        let lastErr;
+        for (let attempt = 1; attempt <= GAP_FILL_MAX_ATTEMPTS; attempt++) {
+          if (this.closed) throw lastErr ?? new Error("closed");
+          try {
+            return await execFile4(larkCli, args);
+          } catch (e) {
+            lastErr = e;
+            if (attempt < GAP_FILL_MAX_ATTEMPTS) {
+              const backoffMs = GAP_FILL_BACKOFF_BASE_MS * 2 ** (attempt - 1);
+              log(
+                `gap-fill: lark-cli pull failed for chat ${chatId} (attempt ${attempt}/${GAP_FILL_MAX_ATTEMPTS}) \u2014 retrying in ${backoffMs}ms: ` + (e instanceof Error ? e.message : String(e))
+              );
+              await this.gapFillSleep(backoffMs);
+            }
+          }
+        }
+        throw lastErr;
+      }
+      /** Drop per-chat unresolved windows older than the replay max age (unrecoverable). */
+      pruneUnresolvedGapWindows(now) {
+        const cutoff = now - UNRESOLVED_WINDOW_MAX_AGE_MS;
+        for (const [chatId, windowStart] of this.unresolvedGapWindowByChat) {
+          if (windowStart < cutoff) this.unresolvedGapWindowByChat.delete(chatId);
+        }
+      }
+      /**
+       * Record (or keep the OLDEST) unresolved window for a chat whose pull failed.
+       * Bounded by chat count: if the map is at capacity and this is a new chat, we
+       * evict the chat with the NEWEST window (least at risk of aging out) so the
+       * oldest at-risk windows survive to be replayed first.
+       */
+      recordUnresolvedGapWindow(chatId, windowStart, log) {
+        const existing = this.unresolvedGapWindowByChat.get(chatId);
+        if (existing !== void 0 && existing <= windowStart) return;
+        if (existing === void 0 && this.unresolvedGapWindowByChat.size >= UNRESOLVED_WINDOW_MAX_CHATS) {
+          let newestChat = null;
+          let newestWs = -Infinity;
+          for (const [c, ws] of this.unresolvedGapWindowByChat) {
+            if (ws > newestWs) {
+              newestWs = ws;
+              newestChat = c;
+            }
+          }
+          if (newestChat !== null && newestWs > windowStart) this.unresolvedGapWindowByChat.delete(newestChat);
+          else if (newestChat !== null) return;
+        }
+        this.unresolvedGapWindowByChat.set(chatId, windowStart);
+        log(
+          `gap-fill: queued unresolved window for chat ${chatId} start=${new Date(windowStart).toISOString()} (tracked chats=${this.unresolvedGapWindowByChat.size})`
+        );
+      }
+      /**
+       * Resolve a chat's unresolved window on a SUCCESSFUL pull — but ONLY if this
+       * run's `coveredFrom` (its lark-cli `--start`) actually reached back to at or
+       * before the tracked windowStart. If the clamp kept `coveredFrom` NEWER than the
+       * tracked window, the old window was NOT really covered → keep it queued so a
+       * later, wider replay can reach it (BLOCKER 2).
+       */
+      resolveUnresolvedGapWindow(chatId, coveredFrom) {
+        const tracked = this.unresolvedGapWindowByChat.get(chatId);
+        if (tracked === void 0) return;
+        if (coveredFrom <= tracked) this.unresolvedGapWindowByChat.delete(chatId);
+      }
       startOpenChatDiscovery(log) {
         if (this.opts.allowedChatIds.size > 0) return;
         if (this.openChatDiscoveryTimer) return;

package/dist/main.js

@@ -15450,7 +15450,7 @@ var require_object_inspect = __commonJS({
       } else if (indexOf(seen, obj) >= 0) {
         return "[Circular]";
       }
-      function inspect(value, from, noIndent) {
+      function inspect2(value, from, noIndent) {
         if (from) {
           seen = $arrSlice.call(seen);
           seen.push(from);
@@ -15468,7 +15468,7 @@ var require_object_inspect = __commonJS({
       }
       if (typeof obj === "function" && !isRegExp(obj)) {
         var name = nameOf(obj);
-        var keys = arrObjKeys(obj, inspect);
+        var keys = arrObjKeys(obj, inspect2);
         return "[Function" + (name ? ": " + name : " (anonymous)") + "]" + (keys.length > 0 ? " { " + $join.call(keys, ", ") + " }" : "");
       }
       if (isSymbol(obj)) {
@@ -15492,16 +15492,16 @@ var require_object_inspect = __commonJS({
         if (obj.length === 0) {
           return "[]";
         }
-        var xs = arrObjKeys(obj, inspect);
+        var xs = arrObjKeys(obj, inspect2);
         if (indent && !singleLineValues(xs)) {
           return "[" + indentedJoin(xs, indent) + "]";
         }
         return "[ " + $join.call(xs, ", ") + " ]";
       }
       if (isError(obj)) {
-        var parts = arrObjKeys(obj, inspect);
+        var parts = arrObjKeys(obj, inspect2);
         if (!("cause" in Error.prototype) && "cause" in obj && !isEnumerable.call(obj, "cause")) {
-          return "{ [" + String(obj) + "] " + $join.call($concat.call("[cause]: " + inspect(obj.cause), parts), ", ") + " }";
+          return "{ [" + String(obj) + "] " + $join.call($concat.call("[cause]: " + inspect2(obj.cause), parts), ", ") + " }";
         }
         if (parts.length === 0) {
           return "[" + String(obj) + "]";
@@ -15519,7 +15519,7 @@ var require_object_inspect = __commonJS({
         var mapParts = [];
         if (mapForEach) {
           mapForEach.call(obj, function(value, key) {
-            mapParts.push(inspect(key, obj, true) + " => " + inspect(value, obj));
+            mapParts.push(inspect2(key, obj, true) + " => " + inspect2(value, obj));
           });
         }
         return collectionOf("Map", mapSize.call(obj), mapParts, indent);
@@ -15528,7 +15528,7 @@ var require_object_inspect = __commonJS({
         var setParts = [];
         if (setForEach) {
           setForEach.call(obj, function(value) {
-            setParts.push(inspect(value, obj));
+            setParts.push(inspect2(value, obj));
           });
         }
         return collectionOf("Set", setSize.call(obj), setParts, indent);
@@ -15543,16 +15543,16 @@ var require_object_inspect = __commonJS({
         return weakCollectionOf("WeakRef");
       }
       if (isNumber(obj)) {
-        return markBoxed(inspect(Number(obj)));
+        return markBoxed(inspect2(Number(obj)));
       }
       if (isBigInt(obj)) {
-        return markBoxed(inspect(bigIntValueOf.call(obj)));
+        return markBoxed(inspect2(bigIntValueOf.call(obj)));
       }
       if (isBoolean2(obj)) {
         return markBoxed(booleanValueOf.call(obj));
       }
       if (isString(obj)) {
-        return markBoxed(inspect(String(obj)));
+        return markBoxed(inspect2(String(obj)));
       }
       if (typeof window !== "undefined" && obj === window) {
         return "{ [object Window] }";
@@ -15561,7 +15561,7 @@ var require_object_inspect = __commonJS({
         return "{ [object globalThis] }";
       }
       if (!isDate(obj) && !isRegExp(obj)) {
-        var ys = arrObjKeys(obj, inspect);
+        var ys = arrObjKeys(obj, inspect2);
         var isPlainObject = gPO ? gPO(obj) === Object.prototype : obj instanceof Object || obj.constructor === Object;
         var protoTag = obj instanceof Object ? "" : "null prototype";
         var stringTag = !isPlainObject && toStringTag && Object(obj) === obj && toStringTag in obj ? $slice.call(toStr(obj), 8, -1) : protoTag ? "Object" : "";
@@ -15815,13 +15815,13 @@ var require_object_inspect = __commonJS({
       var lineJoiner = "\n" + indent.prev + indent.base;
       return lineJoiner + $join.call(xs, "," + lineJoiner) + "\n" + indent.prev;
     }
-    function arrObjKeys(obj, inspect) {
+    function arrObjKeys(obj, inspect2) {
       var isArr = isArray(obj);
       var xs = [];
       if (isArr) {
         xs.length = obj.length;
         for (var i = 0; i < obj.length; i++) {
-          xs[i] = has(obj, i) ? inspect(obj[i], obj) : "";
+          xs[i] = has(obj, i) ? inspect2(obj[i], obj) : "";
         }
       }
       var syms = typeof gOPS === "function" ? gOPS(obj) : [];
@@ -15842,15 +15842,15 @@ var require_object_inspect = __commonJS({
         if (hasShammedSymbols && symMap["$" + key] instanceof Symbol) {
           continue;
         } else if ($test.call(/[^\w$]/, key)) {
-          xs.push(inspect(key, obj) + ": " + inspect(obj[key], obj));
+          xs.push(inspect2(key, obj) + ": " + inspect2(obj[key], obj));
         } else {
-          xs.push(key + ": " + inspect(obj[key], obj));
+          xs.push(key + ": " + inspect2(obj[key], obj));
         }
       }
       if (typeof gOPS === "function") {
         for (var j = 0; j < syms.length; j++) {
           if (isEnumerable.call(obj, syms[j])) {
-            xs.push("[" + inspect(syms[j]) + "]: " + inspect(obj[syms[j]], obj));
+            xs.push("[" + inspect2(syms[j]) + "]: " + inspect2(obj[syms[j]], obj));
           }
         }
       }
@@ -15863,7 +15863,7 @@ var require_object_inspect = __commonJS({
 var require_side_channel_list = __commonJS({
   "node_modules/.pnpm/side-channel-list@1.0.1/node_modules/side-channel-list/index.js"(exports, module) {
     "use strict";
-    var inspect = require_object_inspect();
+    var inspect2 = require_object_inspect();
     var $TypeError = require_type();
     var listGetNode = function(list, key, isDelete) {
       var prev = list;
@@ -15917,7 +15917,7 @@ var require_side_channel_list = __commonJS({
       var channel = {
         assert: function(key) {
           if (!channel.has(key)) {
-            throw new $TypeError("Side channel does not contain " + inspect(key));
+            throw new $TypeError("Side channel does not contain " + inspect2(key));
           }
         },
         "delete": function(key) {
@@ -15981,7 +15981,7 @@ var require_side_channel_map = __commonJS({
     "use strict";
     var GetIntrinsic = require_get_intrinsic();
     var callBound = require_call_bound();
-    var inspect = require_object_inspect();
+    var inspect2 = require_object_inspect();
     var $TypeError = require_type();
     var $Map = GetIntrinsic("%Map%", true);
     var $mapGet = callBound("Map.prototype.get", true);
@@ -15995,7 +15995,7 @@ var require_side_channel_map = __commonJS({
       var channel = {
         assert: function(key) {
           if (!channel.has(key)) {
-            throw new $TypeError("Side channel does not contain " + inspect(key));
+            throw new $TypeError("Side channel does not contain " + inspect2(key));
           }
         },
         "delete": function(key) {
@@ -16037,7 +16037,7 @@ var require_side_channel_weakmap = __commonJS({
     "use strict";
     var GetIntrinsic = require_get_intrinsic();
     var callBound = require_call_bound();
-    var inspect = require_object_inspect();
+    var inspect2 = require_object_inspect();
     var getSideChannelMap = require_side_channel_map();
     var $TypeError = require_type();
     var $WeakMap = GetIntrinsic("%WeakMap%", true);
@@ -16053,7 +16053,7 @@ var require_side_channel_weakmap = __commonJS({
         var channel = {
           assert: function(key) {
             if (!channel.has(key)) {
-              throw new $TypeError("Side channel does not contain " + inspect(key));
+              throw new $TypeError("Side channel does not contain " + inspect2(key));
             }
           },
           "delete": function(key) {
@@ -16109,7 +16109,7 @@ var require_side_channel = __commonJS({
   "node_modules/.pnpm/side-channel@1.1.0/node_modules/side-channel/index.js"(exports, module) {
     "use strict";
     var $TypeError = require_type();
-    var inspect = require_object_inspect();
+    var inspect2 = require_object_inspect();
     var getSideChannelList = require_side_channel_list();
     var getSideChannelMap = require_side_channel_map();
     var getSideChannelWeakMap = require_side_channel_weakmap();
@@ -16119,7 +16119,7 @@ var require_side_channel = __commonJS({
       var channel = {
         assert: function(key) {
           if (!channel.has(key)) {
-            throw new $TypeError("Side channel does not contain " + inspect(key));
+            throw new $TypeError("Side channel does not contain " + inspect2(key));
           }
         },
         "delete": function(key) {
@@ -116182,6 +116182,10 @@ var MAX_MESSAGE_ATTEMPTS = 5;
 var OPEN_CHAT_DISCOVERY_LOOKBACK_MS = 9e4;
 var OPEN_CHAT_DISCOVERY_BOOTSTRAP_LOOKBACK_MS = 30 * 60 * 1e3;
 var PROCESSING_REACTION_EMOJI = "Typing";
+var GAP_FILL_MAX_ATTEMPTS = 3;
+var GAP_FILL_BACKOFF_BASE_MS = 1e3;
+var UNRESOLVED_WINDOW_MAX_CHATS = 50;
+var UNRESOLVED_WINDOW_MAX_AGE_MS = 30 * 60 * 1e3;
 function stripAtMarkup(s) {
   return s.replace(/<at\b[^>]*>.*?<\/at>/gi, "").replace(/<at\b[^>]*\/>/gi, "").trim();
 }
@@ -116382,6 +116386,27 @@ var ChannelClient = class {
    * search space.
    */
   recentlySeenChatIds = /* @__PURE__ */ new Set();
+  /**
+   * PER-CHAT unresolved gapFill windows: chatId → the OLDEST windowStart (ms) for
+   * which that chat's lark-cli history pull still failed after all retries. On a
+   * later gapFill that ACTUALLY pulls this chat, we extend the look-back to cover
+   * its oldest unresolved windowStart and only clear it once the pull truly
+   * reached back that far (its `--start` <= the tracked windowStart). Per-chat (not
+   * a single shared list) so a successful run over chat-set {B} can never falsely
+   * resolve chat A's window (BLOCKER 1), and the look-back-vs-clamp mismatch can
+   * never mark a window resolved before it was reached (BLOCKER 2).
+   *
+   * Bounded: one timestamp per chat (so naturally bounded by #chats), pruned by age
+   * (UNRESOLVED_WINDOW_MAX_AGE_MS — older = unrecoverable from history anyway) and
+   * capped at UNRESOLVED_WINDOW_MAX_CHATS tracked chats.
+   */
+  unresolvedGapWindowByChat = /* @__PURE__ */ new Map();
+  /**
+   * Backoff sleep used by the per-chat history-pull retry. Indirected through a
+   * field purely so tests can observe/await the backoff deterministically; in
+   * production it is the real timer-based {@link sleep}.
+   */
+  gapFillSleep = sleep;
   openChatDiscoveryTimer = null;
   openChatDiscoveryRunning = false;
   openChatDiscoveryBootstrapped = false;
@@ -116403,6 +116428,28 @@ var ChannelClient = class {
     }
     this.opts = opts;
   }
+  /**
+   * TEST SEAM (deletable): override the gap-fill retry backoff sleep so unit
+   * tests can observe the backoff durations and avoid real timers. No-op for
+   * production — the default is the real {@link sleep}. Returns the recorded
+   * backoff arg via the provided callback's own bookkeeping.
+   */
+  setGapFillSleepForTest(fn) {
+    this.gapFillSleep = fn;
+  }
+  /** TEST-ONLY read of the per-chat unresolved-window replay map (chatId → windowStart). */
+  unresolvedGapWindowsForTest() {
+    return new Map(this.unresolvedGapWindowByChat);
+  }
+  /**
+   * TEST-ONLY direct gapFill invocation with an explicit chat-set override —
+   * mirrors exactly how open-chat discovery calls gapFill on a SUBSET of chats.
+   * Used to reproduce the cross-chat-set replay isolation (BLOCKER 1) without
+   * standing up the full discovery timer.
+   */
+  async gapFillForTest(disconnectAt, chatIds) {
+    await this.gapFill(disconnectAt, (s) => console.log(`[channel.client] ${s}`), chatIds);
+  }
   /**
    * Async iterator over inbound events — interface-compatible with LarkClient.
    * Connects the WS on first call. The SDK's policy gate (requireMention +
@@ -116468,7 +116515,25 @@ var ChannelClient = class {
       // ── WS robustness knobs (node-sdk ≥1.64; all OFF by default) ──────────
       // Abort a handshake that hangs on a stuck DNS/proxy/NAT path so the retry
       // loop can try again, instead of waiting indefinitely. Successful TLS
-      // handshakes are tens of ms; 15s is a wide safety margin.
+      // handshakes are tens of ms; 15s is a wide safety margin. KEPT ON: it is
+      // the right behaviour (abort + reconnect beats hanging forever).
+      //
+      // CAVEAT — raw '_WebSocket' 'error' on abort: when this timeout fires the
+      // SDK aborts the underlying ws, which emits a RAW 'error' event on the
+      // socket. That socket is owned privately inside node-sdk's WSClient
+      // (no public `on()`, no accessor for the raw ws — verified against
+      // node-sdk 1.67.0 types: WSClient is not an EventEmitter and keeps the
+      // `_WebSocket` in a closure), so we CANNOT attach a precise 'error'
+      // listener here. With no listener, Node re-throws it as an
+      // uncaughtException → it would kill the whole (multi-bot) process.
+      //   → That raw error is instead caught by the process-level crash guard
+      //     in main.ts (registerCrashGuard: uncaughtException handler that logs
+      //     and never exits). The channel-level `channel.on("error", …)` below
+      //     is a DIFFERENT, higher-level error and does NOT cover this raw case.
+      //   → Residual uncertainty (left for acceptance load-testing): that the
+      //     process guard reliably catches this specific raw abort path under
+      //     real network flap. If a future node-sdk / @larksuite/channel exposes
+      //     the ws or attaches its own listener, prefer that and drop the guard.
       handshakeTimeoutMs: 15e3,
       // Liveness watchdog (SECONDS): if no inbound frame arrives within this
       // window after the last ping, treat the socket as dead and reconnect —
@@ -116585,9 +116650,6 @@ var ChannelClient = class {
     const MAX_GAP_FILL_WINDOW_MS = 5 * 60 * 1e3;
     const BUFFER_MS = 3e4;
     const now = Date.now();
-    const windowStart = Math.max(disconnectAt - BUFFER_MS, now - MAX_GAP_FILL_WINDOW_MS);
-    const startIso = new Date(windowStart).toISOString();
-    const endIso = new Date(now + BUFFER_MS).toISOString();
     const larkCli = this.opts.larkCliPath ?? "lark-cli";
     const profileArgs = this.opts.larkCliProfile ? ["--profile", this.opts.larkCliProfile] : [];
     const botOpenId = this.opts.botOpenId;
@@ -116597,16 +116659,29 @@ var ChannelClient = class {
       ...this.opts.allowedChatIds,
       ...this.recentlySeenChatIds
     ]);
+    this.pruneUnresolvedGapWindows(now);
+    let oldestRelevantUnresolved = Infinity;
+    for (const chatId of gapFillChatIds) {
+      const ws = this.unresolvedGapWindowByChat.get(chatId);
+      if (ws !== void 0 && ws < oldestRelevantUnresolved) oldestRelevantUnresolved = ws;
+    }
+    const hasReplay = oldestRelevantUnresolved !== Infinity;
+    const lookBackFrom = Math.min(disconnectAt, hasReplay ? oldestRelevantUnresolved : disconnectAt);
+    const clampCeilingMs = hasReplay ? UNRESOLVED_WINDOW_MAX_AGE_MS : MAX_GAP_FILL_WINDOW_MS;
+    const windowStart = Math.max(lookBackFrom - BUFFER_MS, now - clampCeilingMs);
+    const startIso = new Date(windowStart).toISOString();
+    const endIso = new Date(now + BUFFER_MS).toISOString();
     if (gapFillChatIds.size === 0) {
       log(
         `gap-fill skipped: no known chats for window=${startIso}..${endIso} (allowedChatIds is empty and no live chat has been seen yet)`
       );
       return;
     }
+    let anyChatFailed = false;
     for (const chatId of gapFillChatIds) {
       if (this.closed) break;
       try {
-        const { stdout } = await execFile(larkCli, [
+        const args = [
           "im",
           "+chat-messages-list",
           "--as",
@@ -116625,7 +116700,8 @@ var ChannelClient = class {
           "json",
           "--no-reactions",
           ...profileArgs
-        ]);
+        ];
+        const { stdout } = await this.execWithRetry(larkCli, args, chatId, log);
         let messages;
         try {
           messages = parseLarkCliMessages(stdout) ?? [];
@@ -116693,16 +116769,91 @@ var ChannelClient = class {
           this.queue.push(ev);
           totalDispatched++;
         }
+        this.resolveUnresolvedGapWindow(chatId, windowStart);
       } catch (e) {
+        anyChatFailed = true;
+        this.recordUnresolvedGapWindow(chatId, windowStart, log);
         log(
-          `gap-fill: lark-cli failed for chat ${chatId}: ` + (e instanceof Error ? e.message : String(e))
+          `gap-fill: lark-cli failed for chat ${chatId} after ${GAP_FILL_MAX_ATTEMPTS} attempt(s): ` + (e instanceof Error ? e.message : String(e))
         );
       }
     }
     log(
-      `gap-fill complete: window=${startIso}..${endIso}, fetched=${totalFetched}, dispatched=${totalDispatched}`
+      `gap-fill complete: window=${startIso}..${endIso}, fetched=${totalFetched}, dispatched=${totalDispatched}` + (anyChatFailed ? ` (some chats failed \u2014 per-chat windows queued for replay)` : ``)
+    );
+  }
+  /**
+   * Run a lark-cli history pull with bounded retries + exponential backoff.
+   * Retries on ANY thrown error (transient TLS timeout being the motivating case),
+   * up to {@link GAP_FILL_MAX_ATTEMPTS}. Backoff is GAP_FILL_BACKOFF_BASE_MS *
+   * 2^(attempt-1) (~1s / 2s). Re-throws the last error if all attempts fail so the
+   * caller can flag the window for replay. Backoff goes through {@link gapFillSleep}
+   * (injectable) so tests can observe it deterministically.
+   */
+  async execWithRetry(larkCli, args, chatId, log) {
+    let lastErr;
+    for (let attempt = 1; attempt <= GAP_FILL_MAX_ATTEMPTS; attempt++) {
+      if (this.closed) throw lastErr ?? new Error("closed");
+      try {
+        return await execFile(larkCli, args);
+      } catch (e) {
+        lastErr = e;
+        if (attempt < GAP_FILL_MAX_ATTEMPTS) {
+          const backoffMs = GAP_FILL_BACKOFF_BASE_MS * 2 ** (attempt - 1);
+          log(
+            `gap-fill: lark-cli pull failed for chat ${chatId} (attempt ${attempt}/${GAP_FILL_MAX_ATTEMPTS}) \u2014 retrying in ${backoffMs}ms: ` + (e instanceof Error ? e.message : String(e))
+          );
+          await this.gapFillSleep(backoffMs);
+        }
+      }
+    }
+    throw lastErr;
+  }
+  /** Drop per-chat unresolved windows older than the replay max age (unrecoverable). */
+  pruneUnresolvedGapWindows(now) {
+    const cutoff = now - UNRESOLVED_WINDOW_MAX_AGE_MS;
+    for (const [chatId, windowStart] of this.unresolvedGapWindowByChat) {
+      if (windowStart < cutoff) this.unresolvedGapWindowByChat.delete(chatId);
+    }
+  }
+  /**
+   * Record (or keep the OLDEST) unresolved window for a chat whose pull failed.
+   * Bounded by chat count: if the map is at capacity and this is a new chat, we
+   * evict the chat with the NEWEST window (least at risk of aging out) so the
+   * oldest at-risk windows survive to be replayed first.
+   */
+  recordUnresolvedGapWindow(chatId, windowStart, log) {
+    const existing = this.unresolvedGapWindowByChat.get(chatId);
+    if (existing !== void 0 && existing <= windowStart) return;
+    if (existing === void 0 && this.unresolvedGapWindowByChat.size >= UNRESOLVED_WINDOW_MAX_CHATS) {
+      let newestChat = null;
+      let newestWs = -Infinity;
+      for (const [c, ws] of this.unresolvedGapWindowByChat) {
+        if (ws > newestWs) {
+          newestWs = ws;
+          newestChat = c;
+        }
+      }
+      if (newestChat !== null && newestWs > windowStart) this.unresolvedGapWindowByChat.delete(newestChat);
+      else if (newestChat !== null) return;
+    }
+    this.unresolvedGapWindowByChat.set(chatId, windowStart);
+    log(
+      `gap-fill: queued unresolved window for chat ${chatId} start=${new Date(windowStart).toISOString()} (tracked chats=${this.unresolvedGapWindowByChat.size})`
     );
   }
+  /**
+   * Resolve a chat's unresolved window on a SUCCESSFUL pull — but ONLY if this
+   * run's `coveredFrom` (its lark-cli `--start`) actually reached back to at or
+   * before the tracked windowStart. If the clamp kept `coveredFrom` NEWER than the
+   * tracked window, the old window was NOT really covered → keep it queued so a
+   * later, wider replay can reach it (BLOCKER 2).
+   */
+  resolveUnresolvedGapWindow(chatId, coveredFrom) {
+    const tracked = this.unresolvedGapWindowByChat.get(chatId);
+    if (tracked === void 0) return;
+    if (coveredFrom <= tracked) this.unresolvedGapWindowByChat.delete(chatId);
+  }
   startOpenChatDiscovery(log) {
     if (this.opts.allowedChatIds.size > 0) return;
     if (this.openChatDiscoveryTimer) return;
@@ -116989,6 +117140,7 @@ function summarizeInput(input) {
   }
   return s.length > 60 ? s.slice(0, 57) + "\u2026" : s;
 }
+var MAX_CARD_ELEMENTS = 50;
 var CHOICE_MARKERS = ["A", "B", "C", "D", "E"];
 function choiceMarker(i) {
   return CHOICE_MARKERS[i] ?? String(i + 1);
@@ -117014,6 +117166,65 @@ function buildChoiceRow(choices) {
 function buildChoiceLegend(choices) {
   return choices.map((c, i) => `**${choiceMarker(i)}.** ${c.label}`).join("\n");
 }
+function plainText(content) {
+  return { tag: "plain_text", content };
+}
+function buildImageElement(block) {
+  const element = {
+    tag: "img",
+    img_key: block.img_key,
+    alt: plainText(block.alt || "\u56FE\u7247\u9884\u89C8"),
+    scale_type: block.mode,
+    preview: block.preview
+  };
+  if (block.title) {
+    element["title"] = plainText(block.title);
+  }
+  return element;
+}
+function canPushElement(elements, reservedTail = 0) {
+  return elements.length + reservedTail < MAX_CARD_ELEMENTS;
+}
+function pushElement(elements, element, reservedTail = 0) {
+  if (!canPushElement(elements, reservedTail)) return false;
+  elements.push(element);
+  return true;
+}
+function pushMarkdownElements(elements, text, reservedTail = 0) {
+  const chunks = chunkMarkdown(text);
+  let truncated = false;
+  for (let i = 0; i < chunks.length; i++) {
+    const content = i === 0 ? chunks[i] : `(\u7EED ${i + 1})
+${chunks[i]}`;
+    if (!pushElement(elements, { tag: "markdown", content }, reservedTail)) {
+      truncated = true;
+      break;
+    }
+  }
+  if (truncated && canPushElement(elements, reservedTail)) {
+    pushElement(elements, {
+      tag: "markdown",
+      content: "_\u5185\u5BB9\u8FC7\u957F,\u540E\u7EED\u90E8\u5206\u5DF2\u7701\u7565_"
+    }, reservedTail);
+  }
+}
+function buildContentBlockElements(blocks, opts = {}) {
+  const elements = [];
+  const mentionPrefix = atMentionMarkdown(opts.mentionOpenId);
+  const reservedTail = opts.reservedTail ?? 0;
+  if (mentionPrefix) {
+    pushMarkdownElements(elements, mentionPrefix, reservedTail);
+  }
+  for (const block of blocks) {
+    if (block.type === "markdown") {
+      const clean = stripLeakedToolMarkup(block.content);
+      if (clean) pushMarkdownElements(elements, clean, reservedTail);
+      continue;
+    }
+    pushElement(elements, buildImageElement(block), reservedTail);
+  }
+  return elements;
+}
 function stripLeakedToolMarkup(text) {
   return text.replace(/<function_calls>[\s\S]*?<\/function_calls>/gi, "").replace(/<invoke\b[^>]*>[\s\S]*?<\/invoke>/gi, "").replace(/<(?:function_calls|invoke|parameter)\b[\s\S]*$/i, "").replace(/<\/?(?:function_calls|invoke|parameter)\b[^>]*>/gi, "").replace(/\n{3,}/g, "\n\n").trim();
 }
@@ -117046,6 +117257,11 @@ function chunkMarkdown(text, maxLen = 2800) {
 }
 function buildCardJson(opts) {
   const elements = [];
+  const hasContentBlocks = !!opts.contentBlocks?.length;
+  const failureReserve = opts.status === "failure" && opts.failureReason ? 2 : 0;
+  const choicesReserve = opts.choices && opts.choices.length ? 4 : 0;
+  const legacyImagesReserve = !hasContentBlocks && opts.imageBlocks?.length ? opts.imageBlocks.length + 1 : 0;
+  const tailReserve = failureReserve + choicesReserve + legacyImagesReserve;
   const TOOL_LINES_CAP = 1;
   if (opts.showToolSummary && opts.toolLines.length > 0 && !opts.hideTools && opts.status !== "success") {
     const total = opts.toolLines.length;
@@ -117053,44 +117269,52 @@ function buildCardJson(opts) {
     const omitted = total - recent.length;
     const content = omitted > 0 ? `_(\u7565\u524D ${omitted} \u6761\u5DE5\u5177\u8C03\u7528)_
 ${recent.join("\n")}` : recent.join("\n");
-    elements.push({
+    pushElement(elements, {
       tag: "markdown",
       content
     });
-    elements.push({ tag: "hr" });
+    pushElement(elements, { tag: "hr" });
   }
   const mentionPrefix = atMentionMarkdown(opts.mentionOpenId);
   const cleanBody = opts.bodyText ? stripLeakedToolMarkup(opts.bodyText) : "";
   const bodyWithMention = [mentionPrefix, cleanBody].filter(Boolean).join("\n\n");
-  if (bodyWithMention) {
-    const chunks = chunkMarkdown(bodyWithMention);
-    for (let i = 0; i < chunks.length; i++) {
-      elements.push({
-        tag: "markdown",
-        content: i === 0 ? chunks[i] : `(\u7EED ${i + 1})
-${chunks[i]}`
-      });
-    }
+  if (hasContentBlocks) {
+    elements.push(
+      ...buildContentBlockElements(opts.contentBlocks ?? [], {
+        mentionOpenId: opts.mentionOpenId,
+        reservedTail: tailReserve
+      })
+    );
+  } else if (bodyWithMention) {
+    pushMarkdownElements(elements, bodyWithMention, tailReserve);
   } else if (opts.status === "thinking") {
-    elements.push({
+    pushElement(elements, {
       tag: "markdown",
       content: "\u{1F914} \u601D\u8003\u4E2D\u2026"
     });
   }
   if (opts.status === "failure" && opts.failureReason) {
-    elements.push({ tag: "hr" });
-    elements.push({
+    pushElement(elements, { tag: "hr" }, choicesReserve);
+    pushElement(elements, {
       tag: "markdown",
       content: `\u26A0\uFE0F **\u9519\u8BEF**: ${opts.failureReason}`
-    });
+    }, choicesReserve);
+  }
+  if (!hasContentBlocks && opts.imageBlocks && opts.imageBlocks.length) {
+    if (bodyWithMention || opts.status === "failure" && opts.failureReason) {
+      pushElement(elements, { tag: "hr" }, choicesReserve);
+    }
+    for (const block of opts.imageBlocks) {
+      pushElement(elements, buildImageElement(block), choicesReserve);
+    }
   }
   if (opts.choices && opts.choices.length) {
-    elements.push({ tag: "hr" });
+    pushElement(elements, { tag: "hr" });
     if (opts.choicePrompt) {
-      elements.push({ tag: "markdown", content: opts.choicePrompt });
+      pushElement(elements, { tag: "markdown", content: opts.choicePrompt });
     }
-    elements.push({ tag: "markdown", content: buildChoiceLegend(opts.choices) });
-    elements.push(buildChoiceRow(opts.choices));
+    pushElement(elements, { tag: "markdown", content: buildChoiceLegend(opts.choices) });
+    pushElement(elements, buildChoiceRow(opts.choices));
   }
   const headerColor = opts.status === "thinking" || opts.status === "streaming" ? "blue" : opts.status === "success" ? "green" : "red";
   const statusText = opts.status === "thinking" ? "\u23F3 \u5904\u7406\u4E2D" : opts.status === "streaming" ? "\u{1F527} \u5904\u7406\u4E2D" : opts.status === "success" ? "\u2705 \u5B8C\u6210" : "\u274C \u51FA\u9519\u4E86";
@@ -117165,6 +117389,8 @@ var CardHandleImpl = class {
       // V2 dynamic-choice buttons — agent-declared, only on finalize.
       choices: opts.choices,
       choicePrompt: opts.choicePrompt,
+      imageBlocks: opts.imageBlocks,
+      contentBlocks: opts.contentBlocks,
       titleOverride: opts.titleOverride,
       // Hide tool-use summary on every finalize — the agent finished, so the
       // Feishu card should present the result/error only. Diagnostics remain in
@@ -117877,6 +118103,9 @@ function renderStateContract(stateFilePath) {
     "- error: \u5931\u8D25\u539F\u56E0(\u642D\u914D status=failed)",
     "- card_title: \u5361\u7247\u6807\u9898\u8986\u76D6(\u53EF\u9009)",
     "- card_color: \u5361\u7247\u914D\u8272(\u53EF\u9009,success/failure/neutral,\u4E5F\u53EF\u76F4\u63A5\u5199 green/red/grey)",
+    "- image_blocks: \u53EF\u9009\u56FE\u7247\u9884\u89C8\u5757\u6570\u7EC4,\u6700\u591A 4 \u4E2A\u3002\u6BCF\u9879 `{img_key, alt?, title?, mode?, preview?}`; `img_key` \u5FC5\u987B\u662F\u5DF2\u4E0A\u4F20/\u53EF\u7528\u4E8E\u5361\u7247\u7684 Feishu \u56FE\u7247 key,`alt` \u7701\u7565\u65F6 bridge \u9ED8\u8BA4\u201C\u56FE\u7247\u9884\u89C8\u201D,`mode` \u53EA\u5141\u8BB8 `crop_center`/`fit_horizontal` \u5E76\u6620\u5C04\u5230 Card JSON 2.0 `scale_type`,`preview` \u9ED8\u8BA4 true\u3002bridge \u4E0D\u8D1F\u8D23\u4E0B\u8F7D/\u4E0A\u4F20/\u9009\u62E9\u56FE\u7247;\u8FD9\u4E9B\u7531\u4F60\u7528 lark-cli \u7B49\u5DE5\u5177\u5148\u5B8C\u6210\u3002",
+    '- content_blocks: \u53EF\u9009\u6709\u5E8F\u6B63\u6587\u5757\u6570\u7EC4,\u6700\u591A 12 \u4E2A block\u3001\u6700\u591A 4 \u4E2A image block\u3002\u53EA\u652F\u6301\u7A84 union:`{type:"markdown", content}` \u548C `{type:"image", img_key, alt?, title?, mode?, preview?}`;\u4E0D\u652F\u6301 raw card JSON\u3002\u7528\u4E8E\u6B63\u6587\u4E0E\u56FE\u7247\u4EA4\u9519\u6392\u7248,\u4F8B\u5982 markdown -> image -> markdown -> image\u3002\u82E5 `content_blocks` \u975E\u7A7A,bridge \u4EE5\u5B83\u4F5C\u4E3A\u4E3B\u6B63\u6587\u5E76\u5FFD\u7565 `last_message` + `image_blocks` \u7684\u6B63\u6587\u6E32\u67D3,\u907F\u514D\u91CD\u590D;\u82E5\u7701\u7565\u5219\u4FDD\u6301\u65E7 `last_message` + `image_blocks` \u884C\u4E3A\u3002',
+    "- scheduled reply / daily social ops review card \u7B49\u9700\u8981\u201C\u5E73\u53F0\u6B63\u6587 + \u5339\u914D\u56FE\u7247\u201D\u540C\u6BB5\u76F8\u90BB\u5C55\u793A\u7684\u573A\u666F,\u5E94\u5148\u53D6\u5F97\u5404\u56FE\u7247 `img_key`,\u518D\u5199 `content_blocks` \u4E3A `\u5E73\u53F0 markdown -> \u5BF9\u5E94 image -> \u4E0B\u4E2A\u5E73\u53F0 markdown -> \u5BF9\u5E94 image`;\u4E0D\u8981\u7528\u5355\u72EC\u8BDD\u9898\u56FE\u7247\u6D88\u606F\u6216\u5C3E\u90E8 `image_blocks` \u4EE3\u66FF\u9A8C\u6536\u9762\u3002",
     "- dev_url / mr_url / \u5176\u4F59\u4E1A\u52A1\u5B57\u6BB5:\u81EA\u7531\u5199\u5165,bridge \u4E0D\u611F\u77E5\u5176\u4E1A\u52A1\u542B\u4E49;\u8981\u8BA9\u8FD0\u8425\u770B\u5230,\u8BF7\u5199\u8FDB last_message",
     "- updated_at: ISO 8601 timestamp",
     "",
@@ -117886,7 +118115,7 @@ function renderStateContract(stateFilePath) {
     "\u6302\u7740\u4E0D\u9000\u51FA = \u5361\u7247\u6C38\u8FDC\u5361\u5728\u300C\u5904\u7406\u4E2D\u300D)\u3002",
     "",
     "\u5361\u7247\u5C55\u793A\u539F\u5219:",
-    "- bridge \u53EF\u80FD\u5728\u8FD0\u884C\u4E2D\u5C55\u793A\u5DE5\u5177\u6458\u8981,\u8FD9\u662F\u901A\u7528\u8FDB\u5EA6\u4FE1\u53F7;\u6700\u7EC8\u6210\u529F\u5361\u7247\u4EE5\u4F60\u7684 last_message \u4E3A\u4E3B\u3002",
+    "- bridge \u53EF\u80FD\u5728\u8FD0\u884C\u4E2D\u5C55\u793A\u5DE5\u5177\u6458\u8981,\u8FD9\u662F\u901A\u7528\u8FDB\u5EA6\u4FE1\u53F7;\u6700\u7EC8\u6210\u529F\u5361\u7247\u4EE5\u4F60\u7684 `content_blocks`(\u82E5\u975E\u7A7A)\u6216 `last_message` \u4E3A\u4E3B\u3002",
     "- \u4E0D\u8981\u4F9D\u8D56 bridge \u4ECE\u8F93\u51FA\u91CC\u89E3\u6790\u4E1A\u52A1\u9636\u6BB5\u3001MR\u3001\u9884\u89C8\u5730\u5740\u6216\u4E0B\u4E00\u6B65\u52A8\u4F5C;\u9700\u8981\u5C55\u793A\u7684\u5185\u5BB9\u4F60\u81EA\u5DF1\u5199\u8FDB last_message\u3002",
     "- \u4E0D\u8981\u6C42\u56FA\u5B9A\u683C\u5F0F\u3002\u6839\u636E\u4EFB\u52A1\u9009\u62E9\u6700\u6E05\u695A\u7684\u8868\u8FBE:\u77ED\u7ED3\u8BBA\u3001\u5206\u70B9\u3001\u8868\u683C\u3001\u94FE\u63A5\u3001\u4E0B\u4E00\u6B65\u95EE\u9898\u90FD\u53EF\u4EE5\u3002",
     "- \u5982\u679C\u672C\u8F6E\u6D89\u53CA repo / \u4EE3\u7801 / \u6587\u6863\u4FEE\u6539,last_message \u5E94\u5305\u542B\u8DB3\u591F\u8BA9\u8FD0\u8425\u9A8C\u6536\u7684\u8BC1\u636E,\u4F8B\u5982\u4F60\u5B9E\u9645\u4F7F\u7528\u7684 workspace/repo\u3001\u5173\u952E diff \u6216\u94FE\u63A5\u3001\u8FD0\u884C\u8FC7\u7684\u6D4B\u8BD5/\u68C0\u67E5\u547D\u4EE4\u548C\u7ED3\u679C\u3002\u5177\u4F53\u8BC1\u636E\u7531\u4EFB\u52A1\u51B3\u5B9A;dogfood E2E \u7684\u4E25\u683C\u6E05\u5355\u53EA\u5728 dogfood guide \u4E2D\u8981\u6C42\u3002",
@@ -117904,6 +118133,7 @@ function renderStateContract(stateFilePath) {
     "  \u6240\u4EE5\u4F60**\u4E0D\u8981\u5728 `last_message` \u91CC\u518D\u624B\u52A8\u5217\u4E00\u904D\u9009\u9879**(\u4F1A\u91CD\u590D);\u6B63\u6587\u53EA\u5199\u95EE\u9898\u80CC\u666F,\u9009\u9879\u4EA4\u7ED9 bridge \u6E32\u67D3",
     "- \u628A `value` \u5199\u6210\u4E00\u53E5\u81EA\u63CF\u8FF0\u7684\u5B8C\u6574\u6307\u4EE4(\u5B83\u5C31\u662F\u4F60\u5C06\u6536\u5230\u7684\u4EFB\u52A1\u6587\u672C),\u4E0D\u8981\u5199\u6210 `optA` \u8FD9\u79CD\u4EE3\u53F7",
     "- \u6CA1\u6709\u9700\u8981\u9009\u7684\u5C31**\u7701\u7565** `choices`(\u5361\u7247\u4FDD\u6301\u5E72\u51C0,\u65E0\u6309\u94AE)",
+    "- \u82E5\u540C\u65F6\u5199 `content_blocks` \u548C `choices`,bridge \u59CB\u7EC8\u628A choices \u6E32\u67D3\u5728\u6B63\u6587\u5185\u5BB9\u4E4B\u540E;\u82E5 `status=failed`,error \u4ECD\u4F1A\u663E\u793A,\u4E0D\u4F1A\u88AB content_blocks \u8986\u76D6\u3002",
     "",
     "\u5199 status=ready \u524D\u5FC5\u987B\u81EA\u5DF1\u7528\u4EE3\u7801\u9A8C\u8FC7(dev server \u7528 curl -I \u770B 200;\u6587\u4EF6 ls/test -f;\u547D\u4EE4\u770B exit code)\u3002bridge \u4E0D\u518D\u66FF\u4F60 probe,\u9A8C\u8BC1\u5B8C\u5168\u662F\u4F60\u7684\u8D23\u4EFB\u3002",
     "\u7B2C\u4E00\u4E2A\u5DE5\u5177\u5931\u8D25\u7ACB\u523B\u5199 status=failed + error,\u522B\u88F8\u5954\u649E\u591A\u4E2A\u5DE5\u5177\u5237\u6210\u8D85\u65F6;\u9700\u6C42\u6709\u6B67\u4E49\u5148\u505C\u4E0B\u5199 status=in_progress + last_message='\u7B49X\u786E\u8BA4',\u522B\u778E\u731C\u5C31\u5F00\u505A\u4E0D\u53EF\u9006\u52A8\u4F5C\u3002",
@@ -118681,6 +118911,48 @@ var optionalUrl = external_exports.preprocess(
   (v) => typeof v === "string" && v.trim() === "" ? void 0 : v,
   external_exports.string().optional()
 );
+var imageAlt = external_exports.preprocess(
+  (v) => typeof v === "string" && v.trim() === "" ? void 0 : v,
+  external_exports.string().trim().min(1).max(200).default("\u56FE\u7247\u9884\u89C8")
+);
+var imageTitle = external_exports.preprocess(
+  (v) => typeof v === "string" && v.trim() === "" ? void 0 : v,
+  external_exports.string().trim().min(1).max(200).optional()
+);
+var ImageBlockSchema = external_exports.object({
+  img_key: external_exports.string().trim().min(1).max(256),
+  alt: imageAlt,
+  title: imageTitle,
+  /**
+   * Agent-facing mode maps directly to Feishu Card JSON 2.0 `scale_type`.
+   * Keep the enum narrow until we have live-card evidence for more modes.
+   */
+  mode: external_exports.enum(["crop_center", "fit_horizontal"]).default("fit_horizontal"),
+  preview: external_exports.boolean().default(true)
+});
+var ContentMarkdownBlockSchema = external_exports.object({
+  type: external_exports.literal("markdown"),
+  content: external_exports.string().trim().min(1).max(2e4)
+});
+var ContentImageBlockSchema = ImageBlockSchema.extend({
+  type: external_exports.literal("image")
+});
+var ContentBlockSchema = external_exports.discriminatedUnion("type", [
+  ContentMarkdownBlockSchema,
+  ContentImageBlockSchema
+]);
+var ContentBlocksSchema = external_exports.array(ContentBlockSchema).max(12).superRefine((blocks, ctx) => {
+  const imageCount = blocks.filter((b) => b.type === "image").length;
+  if (imageCount > 4) {
+    ctx.addIssue({
+      code: external_exports.ZodIssueCode.too_big,
+      type: "array",
+      maximum: 4,
+      inclusive: true,
+      message: "content_blocks supports at most 4 image blocks"
+    });
+  }
+});
 var StateFileSchema = external_exports.object({
   // Thin channel: the bridge only validates `status`. Any other key the bot
   // writes (incl. a legacy `stage`) is a business field — z.object STRIPS
@@ -118757,6 +119029,20 @@ var StateFileSchema = external_exports.object({
    * V1 bots never write this field → V1 cards are byte-for-byte unchanged.
    */
   choices: external_exports.array(external_exports.object({ label: external_exports.string().min(1), value: external_exports.string().min(1) })).max(5).optional(),
+  /**
+   * V2 image blocks (thin-channel). Agents upload or otherwise obtain `img_key`
+   * themselves, then declare generic image previews here. Bridge only renders the
+   * already-declared keys into Feishu Card JSON 2.0 image elements; it does not
+   * download, upload, choose assets, or interpret platform workflows.
+   */
+  image_blocks: external_exports.array(ImageBlockSchema).max(4).optional(),
+  /**
+   * V2 ordered card body blocks (thin-channel). When present and non-empty,
+   * these are the authoritative card body sequence and take precedence over
+   * legacy `last_message` + tail-appended `image_blocks` rendering. Narrow union
+   * only: markdown and image. No raw card JSON escape hatch.
+   */
+  content_blocks: ContentBlocksSchema.optional(),
   /**
    * Optional one-line prompt rendered above the choice buttons (e.g. "选哪个方案?").
    * Rendered VERBATIM, bridge-opaque. Only meaningful alongside `choices`.
@@ -119566,7 +119852,9 @@ var BridgeHandler = class {
                 // reportedState is null when state.json wasn't freshly written
                 // (stale-guard), so stale leftover choices never reappear.
                 choices: reportedState?.choices,
-                choicePrompt: reportedState?.choice_prompt
+                choicePrompt: reportedState?.choice_prompt,
+                imageBlocks: reportedState?.image_blocks,
+                contentBlocks: reportedState?.content_blocks
               });
               await deleteCardFile(worktreePath);
             }
@@ -123852,6 +124140,30 @@ function runtimeRequirementsForBots(bots) {
   });
 }
 
+// src/crashGuard.ts
+import { inspect } from "node:util";
+function handleUncaughtException(err, origin, log = console) {
+  log.error(
+    `[larkway] uncaughtException (origin=${origin}) \u2014 bridge STAYS UP (crash guard). Likely a transient WS handshake-timeout raw socket error; if it recurs, investigate:`,
+    err
+  );
+}
+function handleUnhandledRejection(reason, log = console) {
+  const rendered = reason instanceof Error ? reason : inspect(reason, { depth: 4 });
+  log.error(
+    "[larkway] unhandledRejection \u2014 bridge STAYS UP (crash guard). Full reason:",
+    rendered
+  );
+}
+function registerCrashGuard(log = console) {
+  process.on("uncaughtException", (err, origin) => {
+    handleUncaughtException(err, origin, log);
+  });
+  process.on("unhandledRejection", (reason) => {
+    handleUnhandledRejection(reason, log);
+  });
+}
+
 // src/main.ts
 var STATUS_WRITE_INTERVAL_MS = 3e4;
 var VERSION = resolveLarkwayVersion(import.meta.url);
@@ -124115,6 +124427,7 @@ async function runV2Mode({
   process.on("SIGTERM", () => {
     void shutdown("SIGTERM");
   });
+  registerCrashGuard();
   if (dryRun) {
     console.log("[dry-run] V2 mode \u2014 all bots wired OK, exiting.");
     await Promise.all(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "larkway",
-  "version": "0.3.15",
+  "version": "0.3.17",
   "description": "Thin bridge: Feishu thread to local Claude Code CLI",
   "license": "MIT",
   "author": "Chuck Wu (chuckwu0)",