larkway 0.3.39 → 0.3.41

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.39**
+**Current release: v0.3.41**
 
 ---
 

package/README.zh.md

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

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,74 @@ 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`;
+}
+function realTopicThreadId(threadId) {
+  return typeof threadId === "string" && threadId.startsWith("omt_") ? threadId : void 0;
+}
+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 +117015,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 +117300,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.
    *
@@ -118656,6 +118740,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 {
@@ -118667,6 +118762,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) {
@@ -119114,6 +119213,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");
@@ -119267,6 +119387,7 @@ async function renderPrompt(input) {
     taskHandleTasklistGuid,
     taskHandleClaimed = false,
     taskHandleCandidates = [],
+    taskRoot,
     mtimeFacts = []
   } = input;
   const backend = input.backend ?? "claude";
@@ -119281,7 +119402,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(
@@ -119398,6 +119520,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}`,
@@ -119454,6 +119577,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}`,
@@ -122481,7 +122605,35 @@ 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 = realTopicThreadId(parsed.raw.thread_id);
+        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) {
+                const probeThreadId = realTopicThreadId(info.threadId);
+                taskRootInfo = {
+                  guid: todo.taskGuid,
+                  summary: todo.summaryText,
+                  topicLink: probeThreadId ? buildTopicDeepLink(parsed.chatId, probeThreadId) : void 0
+                };
+                replyInThread = true;
+                replyAnchorId = rootId;
+              }
+            }
+          }
+        }
+      }
       const prototypeConfig = this.deps.botConfig?.response_surface_prototype;
       const cardKitAvailable = isResponseSurfaceCardKitAvailable(
         prototypeConfig,
@@ -122497,7 +122649,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(),
@@ -122568,7 +122720,10 @@ var BridgeHandler = class {
             inputPreview: parsed.text,
             target: {
               chatId: parsed.chatId,
-              threadId: typeof parsed.raw.thread_id === "string" && parsed.raw.thread_id ? parsed.raw.thread_id : void 0,
+              // omt_* only (see realTopicThreadId): passing a reply-chain om_*
+              // id as receive_id_type=thread_id anchored the COT bubble onto a
+              // stray thread on the TRIGGER message (2026-07-08 dogfood).
+              threadId: realTopicThreadId(parsed.raw.thread_id),
               originMessageId
             }
           });
@@ -122596,7 +122751,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",
@@ -122627,7 +122782,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 ?? "",
@@ -122672,7 +122827,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",
@@ -122687,7 +122842,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,
@@ -122924,6 +123079,28 @@ 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 = realTopicThreadId(parsed.raw.thread_id);
+                const probeThreadId = realTopicThreadId(info.threadId);
+                taskRootInfo = {
+                  guid: todo.taskGuid,
+                  summary: todo.summaryText,
+                  topicLink: rawThreadId ? buildTopicDeepLink(parsed.chatId, rawThreadId) : probeThreadId ? buildTopicDeepLink(parsed.chatId, probeThreadId) : void 0
+                };
+              }
+            }
+          }
+          if (taskRootInfo && !taskRootInfo.topicLink && replyAnchorId !== messageId && this.deps.messageLookup) {
+            const refreshed = await this.deps.messageLookup.get(replyAnchorId, { refresh: true }).catch(() => void 0);
+            const refreshedThreadId = realTopicThreadId(refreshed?.threadId);
+            if (refreshedThreadId) {
+              taskRootInfo.topicLink = buildTopicDeepLink(parsed.chatId, refreshedThreadId);
+            }
+          }
           const prompt = await renderPrompt({
             parsed,
             isNewThread: currentIsNewThread,
@@ -122955,6 +123132,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";
@@ -123096,7 +123280,14 @@ 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);
@@ -123241,7 +123432,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,
@@ -123266,7 +123457,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,
@@ -123290,7 +123481,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,
@@ -123314,7 +123505,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,
@@ -123395,7 +123586,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,
@@ -123424,7 +123615,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(
@@ -130014,7 +130205,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;
@@ -130209,6 +130400,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) {
@@ -130222,7 +130416,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 };
   }
@@ -130318,7 +130518,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);
@@ -130335,7 +130535,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;
@@ -130677,6 +130877,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) {
@@ -131438,6 +131678,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) {
@@ -131684,6 +131925,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",
@@ -131942,12 +132184,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,
@@ -131957,12 +132205,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) => {
@@ -131974,12 +132224,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,
@@ -132042,7 +132293,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.
@@ -132091,10 +132342,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;
@@ -132165,6 +132412,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,
@@ -132183,6 +132434,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.39",
+  "version": "0.3.41",
   "description": "Thin bridge: Feishu thread to local Claude Code CLI",
   "license": "MIT",
   "author": "Chuck Wu (chuckwu0)",