larkway 0.3.38 → 0.3.40

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.38**
+**Current release: v0.3.40**
 
 ---
 

package/README.zh.md

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

package/dist/cli/index.js

@@ -112500,6 +112500,72 @@ var init_channelCotClient = __esm({
   }
 });
 
+// src/lark/messageLookupClient.ts
+async function withTimeout2(p, ms, label) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`[channel.msglookup] ${label} timed out after ${ms}ms`)), ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+var LOOKUP_TIMEOUT_MS, CACHE_MAX, ChannelMessageLookupClient;
+var init_messageLookupClient = __esm({
+  "src/lark/messageLookupClient.ts"() {
+    "use strict";
+    LOOKUP_TIMEOUT_MS = 5e3;
+    CACHE_MAX = 200;
+    ChannelMessageLookupClient = class {
+      #resolveChannel;
+      #cache = /* @__PURE__ */ new Map();
+      constructor(opts) {
+        this.#resolveChannel = opts.resolveChannel;
+      }
+      async get(messageId, opts) {
+        if (!opts?.refresh) {
+          const cached = this.#cache.get(messageId);
+          if (cached) return cached;
+        }
+        try {
+          const channel = this.#resolveChannel();
+          if (!channel) return void 0;
+          const req = {
+            url: `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`,
+            method: "GET"
+          };
+          const res = await withTimeout2(
+            channel.rawClient.request(req),
+            LOOKUP_TIMEOUT_MS,
+            `GET message ${messageId}`
+          );
+          if (res.code !== void 0 && res.code !== 0) return void 0;
+          const items = res.data?.["items"];
+          if (!Array.isArray(items) || items.length === 0) return void 0;
+          const item = items[0];
+          const body = item["body"];
+          const info = {
+            msgType: typeof item["msg_type"] === "string" ? item["msg_type"] : void 0,
+            content: body && typeof body === "object" && typeof body["content"] === "string" ? body["content"] : void 0,
+            threadId: typeof item["thread_id"] === "string" && item["thread_id"] ? item["thread_id"] : void 0
+          };
+          if (this.#cache.size >= CACHE_MAX) {
+            const oldest = this.#cache.keys().next().value;
+            if (oldest !== void 0) this.#cache.delete(oldest);
+          }
+          this.#cache.set(messageId, info);
+          return info;
+        } catch {
+          return void 0;
+        }
+      }
+    };
+  }
+});
+
 // src/lark/channelClient.ts
 var channelClient_exports = {};
 __export(channelClient_exports, {
@@ -112660,6 +112726,7 @@ var init_channelClient = __esm({
     init_channelCardKitClient();
     init_channelPostClient();
     init_channelCotClient();
+    init_messageLookupClient();
     execFile4 = promisify4(execFileCallback);
     LEARNED_CHATS_LIMIT = 100;
     SEEN_MESSAGES_LIMIT = 1e3;
@@ -112820,6 +112887,8 @@ var init_channelClient = __esm({
       postClient = null;
       /** Lazily built COT (思维链) client; only requested when a bot enables cot != off. */
       cotClient = null;
+      /** Lazily built single-message lookup client (v4 任务派单 root-type probe). */
+      messageLookupClient = null;
       constructor(opts) {
         if (!opts.appId || !opts.appSecret) {
           throw new Error(
@@ -113103,6 +113172,20 @@ var init_channelClient = __esm({
         }
         return this.cotClient;
       }
+      /**
+       * Return a MessageLookupClient bound to this client's channel handle
+       * (docs/task-handle.md §15.4 — the v4 任务派单 root-type probe). Same lazy
+       * channel resolution and generic rawClient.request() auth path as the COT
+       * client above; strictly best-effort per the client's own contract.
+       */
+      outboundMessageLookupClient() {
+        if (!this.messageLookupClient) {
+          this.messageLookupClient = new ChannelMessageLookupClient({
+            resolveChannel: () => this.channel
+          });
+        }
+        return this.messageLookupClient;
+      }
       /**
        * Return an OutboundPostClient bound to this client's channel handle.
        *
@@ -113793,7 +113876,7 @@ function isTaskRequestTimeoutError(err2) {
   if (err2 instanceof TaskApiError && err2.cause instanceof TaskRequestTimeoutError) return true;
   return false;
 }
-function withTimeout2(promise, ms, label) {
+function withTimeout3(promise, ms, label) {
   let timer;
   const timeout = new Promise((_, reject) => {
     timer = setTimeout(() => reject(new TaskRequestTimeoutError(`${label} timed out after ${ms}ms`)), ms);
@@ -113837,7 +113920,7 @@ var init_client = __esm({
       }
       /** Single choke point for every outbound call — applies the timeout race uniformly. */
       #request(config, label) {
-        return withTimeout2(this.#requester.request(config), this.#timeoutMs, label);
+        return withTimeout3(this.#requester.request(config), this.#timeoutMs, label);
       }
       async getTask(taskGuid) {
         let resp;

package/dist/main.js

@@ -116650,6 +116650,71 @@ function stringField(data, key) {
   return typeof value === "string" ? value : void 0;
 }
 
+// src/lark/messageLookupClient.ts
+function buildTopicDeepLink(chatId, threadId) {
+  const c = encodeURIComponent(chatId);
+  const t = encodeURIComponent(threadId);
+  return `https://applink.feishu.cn/client/thread/open?open_chat_id=${c}&open_thread_id=${t}&openchatid=${c}&openthreadid=${t}&thread_position=-1`;
+}
+var LOOKUP_TIMEOUT_MS = 5e3;
+var CACHE_MAX = 200;
+async function withTimeout2(p, ms, label) {
+  let timer;
+  const timeout = new Promise((_resolve, reject) => {
+    timer = setTimeout(() => reject(new Error(`[channel.msglookup] ${label} timed out after ${ms}ms`)), ms);
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([p, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+var ChannelMessageLookupClient = class {
+  #resolveChannel;
+  #cache = /* @__PURE__ */ new Map();
+  constructor(opts) {
+    this.#resolveChannel = opts.resolveChannel;
+  }
+  async get(messageId, opts) {
+    if (!opts?.refresh) {
+      const cached = this.#cache.get(messageId);
+      if (cached) return cached;
+    }
+    try {
+      const channel = this.#resolveChannel();
+      if (!channel) return void 0;
+      const req = {
+        url: `/open-apis/im/v1/messages/${encodeURIComponent(messageId)}`,
+        method: "GET"
+      };
+      const res = await withTimeout2(
+        channel.rawClient.request(req),
+        LOOKUP_TIMEOUT_MS,
+        `GET message ${messageId}`
+      );
+      if (res.code !== void 0 && res.code !== 0) return void 0;
+      const items = res.data?.["items"];
+      if (!Array.isArray(items) || items.length === 0) return void 0;
+      const item = items[0];
+      const body = item["body"];
+      const info = {
+        msgType: typeof item["msg_type"] === "string" ? item["msg_type"] : void 0,
+        content: body && typeof body === "object" && typeof body["content"] === "string" ? body["content"] : void 0,
+        threadId: typeof item["thread_id"] === "string" && item["thread_id"] ? item["thread_id"] : void 0
+      };
+      if (this.#cache.size >= CACHE_MAX) {
+        const oldest = this.#cache.keys().next().value;
+        if (oldest !== void 0) this.#cache.delete(oldest);
+      }
+      this.#cache.set(messageId, info);
+      return info;
+    } catch {
+      return void 0;
+    }
+  }
+};
+
 // src/lark/channelClient.ts
 var execFile = promisify(execFileCallback);
 var LEARNED_CHATS_LIMIT = 100;
@@ -116947,6 +117012,8 @@ var ChannelClient = class {
   postClient = null;
   /** Lazily built COT (思维链) client; only requested when a bot enables cot != off. */
   cotClient = null;
+  /** Lazily built single-message lookup client (v4 任务派单 root-type probe). */
+  messageLookupClient = null;
   constructor(opts) {
     if (!opts.appId || !opts.appSecret) {
       throw new Error(
@@ -117230,6 +117297,20 @@ var ChannelClient = class {
     }
     return this.cotClient;
   }
+  /**
+   * Return a MessageLookupClient bound to this client's channel handle
+   * (docs/task-handle.md §15.4 — the v4 任务派单 root-type probe). Same lazy
+   * channel resolution and generic rawClient.request() auth path as the COT
+   * client above; strictly best-effort per the client's own contract.
+   */
+  outboundMessageLookupClient() {
+    if (!this.messageLookupClient) {
+      this.messageLookupClient = new ChannelMessageLookupClient({
+        resolveChannel: () => this.channel
+      });
+    }
+    return this.messageLookupClient;
+  }
   /**
    * Return an OutboundPostClient bound to this client's channel handle.
    *
@@ -118525,7 +118606,10 @@ var SessionStore = class _SessionStore {
       lastActiveTs: record.lastActiveTs,
       ...record.senderOpenId !== void 0 ? { senderOpenId: record.senderOpenId } : {},
       ...record.rootText !== void 0 ? { rootText: record.rootText } : {},
-      ...record.chatId !== void 0 ? { chatId: record.chatId } : {}
+      ...record.chatId !== void 0 ? { chatId: record.chatId } : {},
+      // BL-38: only persist when > 0 — a 0/undefined counter is a clean thread,
+      // so passing consecutiveStuckCount: 0 naturally clears the field on reset.
+      ...record.consecutiveStuckCount ? { consecutiveStuckCount: record.consecutiveStuckCount } : {}
     };
     this.#map.set(key, stored);
     await this.#flush();
@@ -118653,6 +118737,17 @@ function extractPostText(value) {
   }
   return "";
 }
+function parseTodoShareContent(rawContent) {
+  try {
+    const parsed = JSON.parse(rawContent);
+    const taskGuid = parsed["task_id"];
+    if (typeof taskGuid !== "string" || taskGuid.length === 0) return null;
+    const summaryText = extractPostText(parsed["summary"]).trim();
+    return { taskGuid, summaryText };
+  } catch {
+    return null;
+  }
+}
 function extractText(event) {
   let parsed;
   try {
@@ -118664,6 +118759,10 @@ function extractText(event) {
     return stripAtPlaceholders(event.content);
   }
   let raw = "";
+  const todo = typeof parsed["task_id"] === "string" ? parseTodoShareContent(event.content) : null;
+  if (todo) {
+    return `[\u98DE\u4E66\u4EFB\u52A1] ${todo.summaryText || "(\u65E0\u6807\u9898)"} (task_guid=${todo.taskGuid})`;
+  }
   if (typeof parsed["text"] === "string") {
     raw = parsed["text"];
   } else if (parsed["content"] !== void 0) {
@@ -119111,6 +119210,27 @@ function renderTaskHandleBlock(tasklistGuid, claimed, candidates) {
     "</task-handle>"
   ];
 }
+function renderTaskRootBlock(taskRoot) {
+  const lines = [
+    "<task-root>",
+    "\u672C\u8BDD\u9898\u7684\u6839\u6D88\u606F\u662F\u4E00\u6761\u98DE\u4E66\u4EFB\u52A1\u5206\u4EAB(\u4EFB\u52A1\u6D3E\u5355\u4E3B\u8DEF\u5F84,docs/task-handle.md \xA715)\u3002",
+    `task_guid: ${taskRoot.guid}`,
+    `task_summary: ${taskRoot.summary || "(\u65E0\u6807\u9898)"}`,
+    ...taskRoot.topicLink ? [`topic_link: ${taskRoot.topicLink}`] : [],
+    `task_root_claimed: ${taskRoot.claimed ? "yes" : "no"}`
+  ];
+  if (taskRoot.claimed) {
+    lines.push(
+      "\u672C\u8BDD\u9898\u5DF2\u8BA4\u9886\u8FD9\u4E2A\u4EFB\u52A1\u3002\u7EF4\u62A4\u9762\u53EA\u6709\u4EFB\u52A1\u8BC4\u8BBA:\u4EC5\u5728\u4EA4\u4ED8/\u5931\u8D25/\u7B49\u62CD\u677F\u4E09\u7C7B\u91CC\u7A0B\u7891\u8282\u70B9\u53D1\u4EFB\u52A1\u8BC4\u8BBA(lark-cli task comments create);\u771F\u6B63\u4EA4\u4ED8\u7684\u90A3\u4E00\u8F6E\u5728 state.json \u7684 task_handle \u91CC\u58F0\u660E done: true,\u5E76\u53D1\u4E00\u6761\u300C\u5DF2\u4EA4\u4ED8,\u770B\u8FC7\u8BF7\u70B9\u5B8C\u6210\u300D\u8BC4\u8BBA\u3002\u4E0D\u8981\u4FEE\u6539\u4EFB\u52A1\u63CF\u8FF0\u3001\u4E0D\u8981\u52FE\u5B8C\u6210/reopen\u2014\u2014\u5B8C\u6210\u6C38\u8FDC\u7531\u4EBA\u5728\u4EFB\u52A1\u4E2D\u5FC3\u70B9\u3002"
+    );
+  } else {
+    lines.push(
+      `\u672C\u8F6E\u8BF7\u987A\u5E26\u9759\u9ED8\u8BA4\u9886,\u5206\u4E24\u6B65:\u2460 \u5148\u8BFB\u4E00\u904D\u8BE5\u4EFB\u52A1\u7684\u73B0\u6709\u8BC4\u8BBA(lark-cli task comments list)\u2014\u2014\u5982\u679C\u5DF2\u6709**\u5176\u4ED6 agent** \u7684\u8BA4\u9886\u58F0\u660E,\u8BF4\u660E\u540C\u8BDD\u9898\u7684\u53E6\u4E00\u4E2A bot \u5DF2\u63A5\u624B,\u672C\u8F6E\u4E0D\u8BA4\u9886\u3001\u4E0D\u58F0\u5F20\u3001\u6B63\u5E38\u56DE\u7B54\u5373\u53EF(\u53CC @ \u7ADE\u6001\u62A4\u680F:\u91CD\u590D\u8BA4\u9886 = \u53CC\u4EFD\u7EF4\u62A4 + \u53CC\u4EFD\u5DE1\u68C0\u9A9A\u6270);\u2461 \u6CA1\u6709\u522B\u4EBA\u8BA4\u9886 \u2192 \u628A\u4E0A\u9762\u7684 task_guid \u5199\u5165 state.json \u7684 task_handle.guid,\u5E76\u53D1\u4E00\u6761\u8BA4\u9886\u8BC4\u8BBA(lark-cli task comments create),\u5185\u5BB9 = \u4E00\u53E5\u8BA4\u9886\u58F0\u660E${taskRoot.topicLink ? " + \u4E0A\u9762\u7684 topic_link(\u7528\u6237\u70B9\u5B83\u76F4\u8FBE\u672C\u8BDD\u9898)" : ""}\u3002\u4E4B\u540E\u7EF4\u62A4\u9762\u53EA\u6709\u4EFB\u52A1\u8BC4\u8BBA(\u4EA4\u4ED8/\u5931\u8D25/\u7B49\u62CD\u677F\u624D\u53D1,\u8FC7\u7A0B\u788E\u788E\u5FF5\u4E0D\u53D1);\u4E0D\u8981\u4FEE\u6539\u4EFB\u52A1\u63CF\u8FF0\u3001\u4E0D\u8981\u52FE\u5B8C\u6210\u2014\u2014\u5B8C\u6210\u6C38\u8FDC\u7531\u4EBA\u70B9\u3002`
+    );
+  }
+  lines.push("</task-root>");
+  return lines;
+}
 function renderRuntimeWarningsBlock(warnings) {
   if (warnings.length === 0) return [];
   const hasMissingLarkCli = warnings.some((warning) => warning.command === "lark-cli");
@@ -119264,6 +119384,7 @@ async function renderPrompt(input) {
     taskHandleTasklistGuid,
     taskHandleClaimed = false,
     taskHandleCandidates = [],
+    taskRoot,
     mtimeFacts = []
   } = input;
   const backend = input.backend ?? "claude";
@@ -119278,7 +119399,8 @@ async function renderPrompt(input) {
   const stateContract = renderStateContract(conventions.stateFilePath);
   const peersBlock = peers && peers.length > 0 ? renderPeersBlock(peers) : [];
   const turnTakingBlock = turn_taking_limit && turn_taking_limit > 0 ? renderTurnTakingHint(turn_taking_limit) : [];
-  const taskHandleBlock = taskHandleTasklistGuid ? renderTaskHandleBlock(taskHandleTasklistGuid, taskHandleClaimed, taskHandleCandidates) : [];
+  const taskHandleBlock = taskHandleTasklistGuid && !taskRoot ? renderTaskHandleBlock(taskHandleTasklistGuid, taskHandleClaimed, taskHandleCandidates) : [];
+  const taskRootBlock = taskRoot ? renderTaskRootBlock(taskRoot) : [];
   const runtimeWarningsBlock = renderRuntimeWarningsBlock(runtimeWarnings);
   const extraRepos = extraRepoPaths ?? conventions.extraRepoPaths ?? [];
   const workspaceBlock = isAgentWorkspace ? await renderAgentWorkspaceBlock(conventions, extraRepos, isNewThread, mtimeFacts) : hasRepo ? renderWorkspaceBlock(
@@ -119395,6 +119517,7 @@ async function renderPrompt(input) {
       ...peersBlock.length > 0 ? ["", ...peersBlock] : [],
       ...turnTakingBlock.length > 0 ? ["", ...turnTakingBlock] : [],
       ...taskHandleBlock.length > 0 ? ["", ...taskHandleBlock] : [],
+      ...taskRootBlock.length > 0 ? ["", ...taskRootBlock] : [],
       "",
       "<user-message>",
       `${parsed.senderOpenId}: ${parsed.text}`,
@@ -119451,6 +119574,7 @@ async function renderPrompt(input) {
     ...peersBlock.length > 0 ? ["", ...peersBlock] : [],
     ...turnTakingBlock.length > 0 ? ["", ...turnTakingBlock] : [],
     ...taskHandleBlock.length > 0 ? ["", ...taskHandleBlock] : [],
+    ...taskRootBlock.length > 0 ? ["", ...taskRootBlock] : [],
     "",
     "<user-message>",
     `${parsed.senderOpenId}: ${parsed.text}`,
@@ -121946,6 +122070,13 @@ function derivePostIdempotencyKey(input) {
 var DEFAULT_CARDKIT_RESPONSE_SURFACE_TIMEOUT_MS = 20 * 60 * 1e3;
 var DEFAULT_CARDKIT_IDLE_TIMEOUT_MS = 3 * 60 * 1e3;
 var COT_BUBBLE_CREATE_BUDGET_MS = 3e3;
+var DEFAULT_STUCK_SESSION_RESET_AFTER = 3;
+function resolveStuckSessionResetAfter() {
+  const raw = process.env.LARKWAY_STUCK_SESSION_RESET_AFTER;
+  if (raw === void 0) return DEFAULT_STUCK_SESSION_RESET_AFTER;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n > 0 ? n : DEFAULT_STUCK_SESSION_RESET_AFTER;
+}
 function summarizeMentionPolicyRules(rules) {
   const counts = /* @__PURE__ */ new Map();
   for (const rule of rules) {
@@ -122471,7 +122602,34 @@ var BridgeHandler = class {
       const existing = this.deps.sessionStore.get(threadId, botId);
       const isNewThread = existing === void 0;
       const isTopLevel = !(typeof parsed.raw.root_id === "string" && parsed.raw.root_id);
-      const replyInThread = isTopLevel;
+      let replyInThread = isTopLevel;
+      let replyAnchorId = messageId;
+      let taskRootInfo;
+      let deferredTaskRootProbe;
+      {
+        const rootId = typeof parsed.raw.root_id === "string" && parsed.raw.root_id ? parsed.raw.root_id : void 0;
+        const rawThreadId = typeof parsed.raw.thread_id === "string" && parsed.raw.thread_id ? parsed.raw.thread_id : void 0;
+        if (rootId && this.deps.messageLookup) {
+          const probe = this.deps.messageLookup.get(rootId).catch(() => void 0);
+          if (rawThreadId) {
+            deferredTaskRootProbe = probe;
+          } else {
+            const info = await probe;
+            if (info?.msgType === "todo" && info.content) {
+              const todo = parseTodoShareContent(info.content);
+              if (todo) {
+                taskRootInfo = {
+                  guid: todo.taskGuid,
+                  summary: todo.summaryText,
+                  topicLink: info.threadId ? buildTopicDeepLink(parsed.chatId, info.threadId) : void 0
+                };
+                replyInThread = true;
+                replyAnchorId = rootId;
+              }
+            }
+          }
+        }
+      }
       const prototypeConfig = this.deps.botConfig?.response_surface_prototype;
       const cardKitAvailable = isResponseSurfaceCardKitAvailable(
         prototypeConfig,
@@ -122487,7 +122645,7 @@ var BridgeHandler = class {
       let startFailurePostFallbackSent = false;
       if (!cardKitAvailable) {
         try {
-          card = await this.deps.cardRenderer.start(messageId, { replyInThread, threadId });
+          card = await this.deps.cardRenderer.start(replyAnchorId, { replyInThread, threadId });
           await recordEvent({
             status: "running",
             startedAt: (/* @__PURE__ */ new Date()).toISOString(),
@@ -122586,7 +122744,7 @@ var BridgeHandler = class {
             try {
               cardKitProgress = await createCardKitProgressHandle({
                 cardKitClient: this.deps.cardKitClient,
-                replyToMessageId: messageId,
+                replyToMessageId: replyAnchorId,
                 replyInThread,
                 facts: {
                   botId: this.deps.botConfig?.id ?? "v1-default",
@@ -122617,7 +122775,7 @@ var BridgeHandler = class {
                 status: "message_sent",
                 cardId: cardKitProgress.cardId,
                 messageId: cardKitProgress.messageId,
-                replyToMessageId: messageId,
+                replyToMessageId: replyAnchorId,
                 chatId: parsed.chatId,
                 threadId,
                 botId: this.deps.botConfig?.id ?? "",
@@ -122662,7 +122820,7 @@ var BridgeHandler = class {
           }
           if (!card && cardKitStartFailed) {
             try {
-              card = await this.deps.cardRenderer.start(messageId, { replyInThread, threadId });
+              card = await this.deps.cardRenderer.start(replyAnchorId, { replyInThread, threadId });
               await this.deps.client.removeProcessingReaction?.(messageId);
               await recordEvent({
                 status: "running",
@@ -122677,7 +122835,7 @@ var BridgeHandler = class {
               );
               const postFallback = await createOnlyPostFallback({
                 postClient: this.deps.postClient,
-                replyToMessageId: messageId,
+                replyToMessageId: replyAnchorId,
                 replyInThread,
                 botId: this.deps.botConfig?.id ?? "v1-default",
                 threadId,
@@ -122914,6 +123072,26 @@ var BridgeHandler = class {
               console.warn("[bridge.handler] live-roster resolve failed (using static peers):", err);
             }
           }
+          if (deferredTaskRootProbe) {
+            const info = await deferredTaskRootProbe;
+            if (info?.msgType === "todo" && info.content) {
+              const todo = parseTodoShareContent(info.content);
+              if (todo) {
+                const rawThreadId = typeof parsed.raw.thread_id === "string" && parsed.raw.thread_id ? parsed.raw.thread_id : void 0;
+                taskRootInfo = {
+                  guid: todo.taskGuid,
+                  summary: todo.summaryText,
+                  topicLink: rawThreadId ? buildTopicDeepLink(parsed.chatId, rawThreadId) : info.threadId ? buildTopicDeepLink(parsed.chatId, info.threadId) : void 0
+                };
+              }
+            }
+          }
+          if (taskRootInfo && !taskRootInfo.topicLink && replyAnchorId !== messageId && this.deps.messageLookup) {
+            const refreshed = await this.deps.messageLookup.get(replyAnchorId, { refresh: true }).catch(() => void 0);
+            if (refreshed?.threadId) {
+              taskRootInfo.topicLink = buildTopicDeepLink(parsed.chatId, refreshed.threadId);
+            }
+          }
           const prompt = await renderPrompt({
             parsed,
             isNewThread: currentIsNewThread,
@@ -122945,6 +123123,13 @@ var BridgeHandler = class {
             taskHandleTasklistGuid: this.deps.botConfig?.taskHandle?.tasklistGuid,
             taskHandleClaimed: this.deps.taskHandleClaimedLookup?.(threadId) ?? false,
             taskHandleCandidates: this.deps.taskHandleCandidatesLookup?.() ?? [],
+            taskRoot: taskRootInfo ? {
+              ...taskRootInfo,
+              // Exact-guid comparison (see taskHandleClaimGuidLookup's doc);
+              // falls back to the boolean lookup only when the precise one
+              // isn't wired (older embedding code).
+              claimed: this.deps.taskHandleClaimGuidLookup ? this.deps.taskHandleClaimGuidLookup(threadId) === taskRootInfo.guid : this.deps.taskHandleClaimedLookup?.(threadId) ?? false
+            } : void 0,
             mtimeFacts
           });
           const backend = this.deps.botConfig?.backend ?? "claude";
@@ -123086,40 +123271,19 @@ var BridgeHandler = class {
                   botId,
                   threadId,
                   chatId: parsed.chatId,
-                  taskGuid: claimedTaskGuid
+                  taskGuid: claimedTaskGuid,
+                  // v4 任务派单 (docs/task-handle.md §15.3): a claim on the very
+                  // task this thread's ROOT message shares is comment-mode —
+                  // maintenance goes through task comments only (share-to-chat
+                  // grants read+comment; no tasklist/editor rights needed, and
+                  // completion is ALWAYS ticked by the human). Mechanical
+                  // equality check, not a judgment call.
+                  mode: taskRootInfo?.guid === claimedTaskGuid ? "comment" : void 0
                 });
               } catch (err) {
                 console.warn("[bridge.handler] taskHandleClaim hook failed (continuing):", err);
               }
             }
-            const now = Date.now();
-            if (sessionId !== void 0 && currentExisting === void 0) {
-              await this.deps.sessionStore.put({
-                threadId,
-                sessionId,
-                botId,
-                createdTs: now,
-                lastActiveTs: now,
-                senderOpenId,
-                ...isTopLevel ? { rootText: parsed.text.slice(0, 200), chatId: parsed.chatId } : {}
-              });
-            } else if (sessionId !== void 0 && currentExisting !== void 0) {
-              await this.deps.sessionStore.put({
-                threadId,
-                sessionId,
-                botId,
-                createdTs: currentExisting.createdTs,
-                lastActiveTs: now,
-                senderOpenId,
-                rootText: currentExisting.rootText,
-                chatId: currentExisting.chatId
-              });
-            } else if (currentExisting !== void 0 && sessionId === void 0) {
-              await this.deps.sessionStore.put({
-                ...currentExisting,
-                lastActiveTs: now
-              });
-            }
             const reportedStatus = reportedState?.status;
             const reportedError = reportedState?.error;
             const cardKitTimeoutFailure = interruptedByIdle && reportedStatus !== "ready" && reportedStatus !== "failed";
@@ -123149,10 +123313,53 @@ var BridgeHandler = class {
                 reason: failureReason
               });
             }
+            const stuckResetAfter = resolveStuckSessionResetAfter();
+            const prevStuckCount = currentExisting?.consecutiveStuckCount ?? 0;
+            const nextStuckCount = cardKitTimeoutFailure ? prevStuckCount + 1 : success ? 0 : prevStuckCount;
+            const stuckResetTriggered = cardKitTimeoutFailure && nextStuckCount >= stuckResetAfter;
+            const now = Date.now();
+            if (stuckResetTriggered) {
+              await this.deps.sessionStore.delete(threadId, botId);
+              console.info(
+                `[bridge.handler] BL-38 stuck-session reset: thread=${threadId} bot=${botId} consecutiveStuckCount=${nextStuckCount} (>= ${stuckResetAfter}) \u2014 dropped session record; next @ starts fresh`
+              );
+            } else if (sessionId !== void 0 && currentExisting === void 0) {
+              await this.deps.sessionStore.put({
+                threadId,
+                sessionId,
+                botId,
+                createdTs: now,
+                lastActiveTs: now,
+                senderOpenId,
+                // BL-38: a brand-new thread that idle-killed on its very first turn
+                // starts the counter at 1 (0 when clean; only persisted when > 0).
+                consecutiveStuckCount: nextStuckCount,
+                ...isTopLevel ? { rootText: parsed.text.slice(0, 200), chatId: parsed.chatId } : {}
+              });
+            } else if (sessionId !== void 0 && currentExisting !== void 0) {
+              await this.deps.sessionStore.put({
+                threadId,
+                sessionId,
+                botId,
+                createdTs: currentExisting.createdTs,
+                lastActiveTs: now,
+                senderOpenId,
+                rootText: currentExisting.rootText,
+                chatId: currentExisting.chatId,
+                // BL-38: +1 on an idle-stuck turn, 0 (cleared) on any clean turn.
+                consecutiveStuckCount: nextStuckCount
+              });
+            } else if (currentExisting !== void 0 && sessionId === void 0) {
+              await this.deps.sessionStore.put({
+                ...currentExisting,
+                lastActiveTs: now,
+                consecutiveStuckCount: nextStuckCount
+              });
+            }
             const fallbackAnswer = trustedAnswerText.trim() || cardKitProgress?.answerText.trim() || "";
             const noOutputFallback = "\u26A0\uFE0F \u672C\u8F6E agent \u6CA1\u6709\u4EA7\u51FA\u6B63\u6587\uFF0C\u4E5F\u6CA1\u6709\u5199\u5165\u6709\u6548\u72B6\u6001(state.json)\u3002\n" + (result.exitCode !== 0 ? `agent \u8FDB\u7A0B\u5F02\u5E38\u9000\u51FA(exit code ${result.exitCode})\u3002
 ` : "") + "\u4E0B\u4E00\u6B65\uFF1A\u6362\u4E2A\u8BF4\u6CD5\u91CD\u8BD5\uFF0C\u6216\u65B0\u5F00\u4E00\u4E2A\u8BDD\u9898\u7EE7\u7EED\uFF1B\u82E5\u53CD\u590D\u5982\u6B64\uFF0C\u8BF7\u8BA9\u7EF4\u62A4\u8005\u67E5\u770B\u8BE5 session \u65E5\u5FD7\u3002";
-            const cardBody = cardKitTimeoutFailure ? "\u26A0\uFE0F \u672C\u8F6E\u88AB\u4E2D\u65AD\uFF08\u957F\u65F6\u95F4\u65E0\u6D3B\u6027\uFF0C\u5224\u5B9A\u5361\u6B7B\uFF09\uFF0C\u672A\u5B8C\u6210\u3002\u8BF7\u91CD\u8BD5\u3002" : reportedState?.last_message ?? (fallbackAnswer ? fallbackAnswer : noOutputFallback);
+            const cardBody = stuckResetTriggered ? "\u26A0\uFE0F \u672C\u8F6E\u88AB\u4E2D\u65AD\uFF08\u957F\u65F6\u95F4\u65E0\u6D3B\u6027\uFF0C\u5224\u5B9A\u5361\u6B7B\uFF09\u3002\u8FDE\u7EED\u591A\u6B21\u5361\u6B7B\uFF0C\u5DF2\u91CD\u7F6E\u672C\u8BDD\u9898\u4E0A\u4E0B\u6587 \u2014\u2014 \u4E0B\u6B21 @ \u6211\u5C06\u5168\u65B0\u5F00\u59CB\uFF0C\u8BF7\u628A\u9700\u6C42\u91CD\u65B0\u8BF4\u4E00\u904D\u3002" : cardKitTimeoutFailure ? "\u26A0\uFE0F \u672C\u8F6E\u88AB\u4E2D\u65AD\uFF08\u957F\u65F6\u95F4\u65E0\u6D3B\u6027\uFF0C\u5224\u5B9A\u5361\u6B7B\uFF09\uFF0C\u672A\u5B8C\u6210\u3002\u8BF7\u91CD\u8BD5\u3002" : reportedState?.last_message ?? (fallbackAnswer ? fallbackAnswer : noOutputFallback);
             const noReportThisTurn = reportedState === null;
             const neutralTitle = noReportThisTurn && success && !failureReason ? "\u{1F4AC} \u5DF2\u56DE\u590D" : void 0;
             const baseCardPayload = {
@@ -123216,7 +123423,7 @@ var BridgeHandler = class {
                 console.warn("[bridge.handler] CardKit finalize failed; using card fallback:", err);
                 cardKitProgress.close();
                 try {
-                  card = await this.deps.cardRenderer.start(messageId, { replyInThread, threadId });
+                  card = await this.deps.cardRenderer.start(replyAnchorId, { replyInThread, threadId });
                   await writeCardFile(worktreePath, {
                     messageId: card.messageId,
                     chatId: parsed.chatId,
@@ -123241,7 +123448,7 @@ var BridgeHandler = class {
                 } catch (legacyErr) {
                   const postFallback = await createOnlyPostFallback({
                     postClient: this.deps.postClient,
-                    replyToMessageId: messageId,
+                    replyToMessageId: replyAnchorId,
                     replyInThread,
                     botId: this.deps.botConfig?.id ?? "v1-default",
                     threadId,
@@ -123265,7 +123472,7 @@ var BridgeHandler = class {
             } else {
               if (!card) {
                 try {
-                  card = await this.deps.cardRenderer.start(messageId, { replyInThread, threadId });
+                  card = await this.deps.cardRenderer.start(replyAnchorId, { replyInThread, threadId });
                   try {
                     await writeCardFile(worktreePath, {
                       messageId: card.messageId,
@@ -123289,7 +123496,7 @@ var BridgeHandler = class {
                   ].filter((part) => !!part).join("; ");
                   const postFallback = await createOnlyPostFallback({
                     postClient: this.deps.postClient,
-                    replyToMessageId: messageId,
+                    replyToMessageId: replyAnchorId,
                     replyInThread,
                     botId: this.deps.botConfig?.id ?? "v1-default",
                     threadId,
@@ -123370,7 +123577,7 @@ var BridgeHandler = class {
         const createHardFailurePostFallback = async (failureReason) => {
           const fallback = await createOnlyPostFallback({
             postClient: this.deps.postClient,
-            replyToMessageId: messageId,
+            replyToMessageId: replyAnchorId,
             replyInThread,
             botId: this.deps.botConfig?.id ?? "v1-default",
             threadId,
@@ -123399,7 +123606,7 @@ var BridgeHandler = class {
               cardKitFinalizeErr
             );
             try {
-              card = await this.deps.cardRenderer.start(messageId, { replyInThread, threadId });
+              card = await this.deps.cardRenderer.start(replyAnchorId, { replyInThread, threadId });
             } catch (cardStartErr) {
               console.error("[bridge.handler] failure card start also failed:", cardStartErr);
               await createHardFailurePostFallback(
@@ -129989,7 +130196,7 @@ function isStallNudgeState(value) {
 function isTaskHandleRecord(value) {
   if (typeof value !== "object" || value === null) return false;
   const v = value;
-  return typeof v["threadId"] === "string" && typeof v["taskGuid"] === "string" && typeof v["chatId"] === "string" && typeof v["claimedTs"] === "number" && (v["lastSeenCommentId"] === void 0 || typeof v["lastSeenCommentId"] === "string") && (v["lastTurnOutcome"] === void 0 || v["lastTurnOutcome"] === "completed" || v["lastTurnOutcome"] === "failed") && (v["stallNudge"] === void 0 || isStallNudgeState(v["stallNudge"])) && (v["stallSuppressUntilActivityAfter"] === void 0 || typeof v["stallSuppressUntilActivityAfter"] === "number") && (v["lastTurnMentions"] === void 0 || Array.isArray(v["lastTurnMentions"]) && v["lastTurnMentions"].every((m) => typeof m === "string")) && (v["lastTurnMentionsAt"] === void 0 || typeof v["lastTurnMentionsAt"] === "number");
+  return typeof v["threadId"] === "string" && typeof v["taskGuid"] === "string" && typeof v["chatId"] === "string" && typeof v["claimedTs"] === "number" && (v["lastSeenCommentId"] === void 0 || typeof v["lastSeenCommentId"] === "string") && (v["lastTurnOutcome"] === void 0 || v["lastTurnOutcome"] === "completed" || v["lastTurnOutcome"] === "failed") && (v["stallNudge"] === void 0 || isStallNudgeState(v["stallNudge"])) && (v["stallSuppressUntilActivityAfter"] === void 0 || typeof v["stallSuppressUntilActivityAfter"] === "number") && (v["lastTurnMentions"] === void 0 || Array.isArray(v["lastTurnMentions"]) && v["lastTurnMentions"].every((m) => typeof m === "string")) && (v["lastTurnMentionsAt"] === void 0 || typeof v["lastTurnMentionsAt"] === "number") && (v["mode"] === void 0 || v["mode"] === "comment") && (v["doneDeclared"] === void 0 || typeof v["doneDeclared"] === "boolean");
 }
 var TaskHandleStore = class _TaskHandleStore {
   #filePath;
@@ -130184,6 +130391,9 @@ var TaskHandleStore = class _TaskHandleStore {
     await this.update(input.threadId, (existing) => {
       if (existing && existing.taskGuid === input.taskGuid) {
         claimed = true;
+        if (input.mode === "comment" && existing.mode === void 0) {
+          return { ...existing, mode: "comment" };
+        }
         return existing;
       }
       if (input.onlyIfThreadUnclaimed && existing !== void 0) {
@@ -130197,7 +130407,13 @@ var TaskHandleStore = class _TaskHandleStore {
         }
       }
       claimed = true;
-      return { threadId: input.threadId, taskGuid: input.taskGuid, chatId: input.chatId, claimedTs: Date.now() };
+      return {
+        threadId: input.threadId,
+        taskGuid: input.taskGuid,
+        chatId: input.chatId,
+        claimedTs: Date.now(),
+        ...input.mode ? { mode: input.mode } : {}
+      };
     });
     return { claimed, reason };
   }
@@ -130293,7 +130509,7 @@ function isTaskRequestTimeoutError(err) {
   if (err instanceof TaskApiError && err.cause instanceof TaskRequestTimeoutError) return true;
   return false;
 }
-function withTimeout2(promise, ms, label) {
+function withTimeout3(promise, ms, label) {
   let timer;
   const timeout = new Promise((_, reject) => {
     timer = setTimeout(() => reject(new TaskRequestTimeoutError(`${label} timed out after ${ms}ms`)), ms);
@@ -130310,7 +130526,7 @@ var TaskListClient = class {
   }
   /** Single choke point for every outbound call — applies the timeout race uniformly. */
   #request(config, label) {
-    return withTimeout2(this.#requester.request(config), this.#timeoutMs, label);
+    return withTimeout3(this.#requester.request(config), this.#timeoutMs, label);
   }
   async getTask(taskGuid) {
     let resp;
@@ -130652,6 +130868,46 @@ async function applyTaskHandleWriteback(patch, deps) {
       return;
     }
     const isCompleted = !!task.completedAt && task.completedAt !== "0";
+    if (record.mode === "comment") {
+      switch (patch.status) {
+        case "received": {
+          if (record.doneDeclared) {
+            await deps.store.update(
+              patch.threadId,
+              (current) => current ? { ...current, doneDeclared: void 0 } : current
+            );
+          }
+          break;
+        }
+        case "completed": {
+          const mentionedPeerBotIds = patch.mentionedPeerBotIds && patch.mentionedPeerBotIds.length > 0 ? patch.mentionedPeerBotIds : void 0;
+          const mentionAnchorMs = patch.turnReceivedAt ?? Date.now();
+          await deps.store.update(
+            patch.threadId,
+            (current) => current ? {
+              ...current,
+              lastTurnOutcome: "completed",
+              lastTurnMentions: mentionedPeerBotIds,
+              lastTurnMentionsAt: mentionedPeerBotIds ? mentionAnchorMs : void 0,
+              // Agent declared delivery — its own "已交付" comment is the
+              // user-facing artifact; bridge just stops patrolling the
+              // "delivered, human hasn't ticked complete yet" window.
+              ...patch.agentDeclaredDone === true ? { doneDeclared: true } : {}
+            } : current
+          );
+          break;
+        }
+        case "failed": {
+          await deps.store.update(
+            patch.threadId,
+            (current) => current ? { ...current, lastTurnOutcome: "failed", lastTurnMentions: void 0, lastTurnMentionsAt: void 0 } : current
+          );
+          await deps.client.addComment(record.taskGuid, renderFailureComment(patch.failureReason));
+          break;
+        }
+      }
+      return;
+    }
     switch (patch.status) {
       case "received": {
         if (isCompleted) {
@@ -131413,6 +131669,7 @@ var StallDetector = class {
   async #pollOne(threadId) {
     let record = this.#deps.store.get(threadId);
     if (!record) return;
+    if (record.doneDeclared) return;
     const lastActiveTs = this.#deps.getLastActiveTs(threadId) ?? record.claimedTs;
     const now = Date.now();
     if (record.stallSuppressUntilActivityAfter !== void 0 && lastActiveTs <= record.stallSuppressUntilActivityAfter) {
@@ -131659,6 +131916,7 @@ var StallDetector = class {
         }
       } : r
     );
+    if (record.mode === "comment") return;
     const logSummary = `\u505C\u6EDE\u5524\u9192 #${prospectiveCount}(${this.#nudgeReasonLabel(reason, dueMs)})`;
     const nextDescription = mergeDescriptionSnapshot(task.description, {
       status: "in_progress",
@@ -131917,12 +132175,18 @@ async function runV2Mode({
     let taskHandleLifecycle;
     let taskHandleClaim;
     let taskHandleClaimedLookup;
+    let taskHandleClaimGuidLookup;
     let taskHandleCandidatesLookup;
     let taskCommentPoller;
     let stallDetector;
     {
       const guid = bot.taskHandle?.tasklistGuid ?? await readTeamTasklistGuid(resolveTaskTeamRegistryPath());
-      if (guid) {
+      if (!guid) {
+        console.log(
+          `[larkway] bot "${bot.id}": \u4EFB\u52A1\u6D3E\u5355\u4E3B\u8DEF\u5F84\u5DF2\u5C31\u7EEA(\u5EFA\u4EFB\u52A1\u2192\u53D1\u9001\u5230\u7FA4\u2192@ \u672C bot,\u96F6\u914D\u7F6E)\u3002\u8BDD\u9898\u8F6C\u4EFB\u52A1\u8F85\u8DEF\u5F84\u7684\u5171\u4EAB\u6E05\u5355\u672A\u914D\u7F6E(taskHandle.tasklistGuid \u7F3A\u5931,\u5171\u4EAB\u6CE8\u518C\u6587\u4EF6\u91CC\u4E5F\u6CA1\u6709);\u60F3\u542F\u7528:\u8FD0\u884C larkway tasklist-init(\u89C1 docs/task-handle.md \xA77/\xA715)\u3002`
+        );
+      }
+      {
         const taskSdkClient = new import_node_sdk2.Client({
           appId: bot.app_id,
           appSecret,
@@ -131932,12 +132196,14 @@ async function runV2Mode({
           request: (config2) => taskSdkClient.request(config2)
         };
         const taskListClient = new TaskListClient(taskRequester);
-        await taskListClient.addTasklistMembers(guid, [{ id: bot.app_id, type: "app", role: "editor" }]).catch((err) => {
-          console.warn(
-            `[larkway] bot "${bot.id}": self-join tasklist ${guid} as editor failed (continuing, best-effort): ${compactErrorText(err)}`
-          );
-        });
-        effectiveTaskHandleTasklistGuid = guid;
+        if (guid) {
+          await taskListClient.addTasklistMembers(guid, [{ id: bot.app_id, type: "app", role: "editor" }]).catch((err) => {
+            console.warn(
+              `[larkway] bot "${bot.id}": self-join tasklist ${guid} as editor failed (continuing, best-effort): ${compactErrorText(err)}`
+            );
+          });
+          effectiveTaskHandleTasklistGuid = guid;
+        }
         const taskHandleStore = await TaskHandleStore.load(resolveTaskHandlesPath(bot.id));
         taskHandleLifecycle = (patch) => applyTaskHandleWriteback(patch, { store: taskHandleStore, client: taskListClient });
         taskHandleClaim = async (patch) => {
@@ -131949,12 +132215,13 @@ async function runV2Mode({
           }
         };
         taskHandleClaimedLookup = (threadId) => taskHandleStore.get(threadId) !== void 0;
-        {
+        taskHandleClaimGuidLookup = (threadId) => taskHandleStore.get(threadId)?.taskGuid;
+        if (guid) {
           const group = tasklistGuidGroups.get(guid) ?? { client: taskListClient, clientOwnerBotId: bot.id, bots: [] };
           group.bots.push({ botId: bot.id, sessionStore, taskHandleStore });
           tasklistGuidGroups.set(guid, group);
+          taskHandleCandidatesLookup = () => tasklistPollersByGuid.get(guid)?.getCandidates() ?? [];
         }
-        taskHandleCandidatesLookup = () => tasklistPollersByGuid.get(guid)?.getCandidates() ?? [];
         taskCommentPoller = new CommentPoller({
           store: taskHandleStore,
           client: taskListClient,
@@ -132017,7 +132284,7 @@ async function runV2Mode({
               // taskHandleCandidatesLookup above (the poller for `guid` is
               // constructed AFTER this whole per-bot loop finishes, but this
               // closure is only ever INVOKED later, at poll time).
-              getTaskDueMs: (taskGuid) => tasklistPollersByGuid.get(guid)?.getDueTimestamp(taskGuid),
+              getTaskDueMs: (taskGuid) => guid ? tasklistPollersByGuid.get(guid)?.getDueTimestamp(taskGuid) : void 0,
               // Round-2 adversarial review fix: THIS bot's own receipt signal
               // (not a peer's) — disambiguates a pending-nudge confirmation
               // timeout from a nudge turn merely queued behind the semaphore.
@@ -132066,10 +132333,6 @@ async function runV2Mode({
           );
           stallDetector.start();
         }
-      } else {
-        console.log(
-          `[larkway] bot "${bot.id}": \u8BDD\u9898\u2194\u4EFB\u52A1\u53E5\u67C4\u672A\u914D\u7F6E(taskHandle.tasklistGuid \u7F3A\u5931,\u5171\u4EAB\u6CE8\u518C\u6587\u4EF6\u91CC\u4E5F\u6CA1\u6709)\u3002\u60F3\u542F\u7528:\u8FD0\u884C larkway tasklist-init(\u6216\u5BF9\u4F60\u7684 agent \u8BF4"\u5E2E\u6211\u914D\u7F6E Agent Team")(\u89C1 docs/task-handle.md \xA77)\u3002`
-        );
       }
     }
     let codexPool;
@@ -132140,6 +132403,10 @@ async function runV2Mode({
       cardKitClient,
       cotClient,
       postClient,
+      // v4 任务派单 root-type probe (docs/task-handle.md §15.4) — lazy channel
+      // resolution, best-effort by the client's own contract, no config gate
+      // (the probe only ever fires on quote-reply turns).
+      messageLookup: client.outboundMessageLookupClient(),
       gitlabToken: effectiveGitlabToken,
       agentMemory: bot.agent_memory,
       larkCliProfile,
@@ -132158,6 +132425,7 @@ async function runV2Mode({
       taskHandleLifecycle,
       taskHandleClaim,
       taskHandleClaimedLookup,
+      taskHandleClaimGuidLookup,
       taskHandleCandidatesLookup
     });
     handlersByBotId.set(bot.id, handler);

package/package.json

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