larkway 0.3.32 → 0.3.33

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.30**
+**Current release: v0.3.33**
 
 ---
 

package/README.zh.md

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

package/dist/main.js

@@ -119133,7 +119133,30 @@ var StateFileSchema = external_exports.object({
    * ignored and the legacy card path remains authoritative.
    */
   response_surface: ResponseSurfaceStateSchema.optional(),
-  updated_at: external_exports.string()
+  /**
+   * Freshness signal for the handler's stale-guard (it compares this against a
+   * pre-run snapshot to decide whether the bot rewrote state THIS turn).
+   *
+   * **OPTIONAL by thin-channel principle.** This used to be the ONE hard-required
+   * field, so a bot that wrote a perfectly good `status` + `last_message` but
+   * omitted `updated_at` had its ENTIRE state discarded → the card stranded on
+   * "本轮没有拿到 agent 的新回复" every single turn (2026-07-02 排障: one shared
+   * topic reproduced this on every @). Same failure class as the old
+   * `z.string().url()` mr_url and the strict `stage`/`card_color` enums.
+   *
+   * When absent, {@link readStateFileDetailed} server-stamps it from the file's
+   * mtime — which advances only on a real rewrite, so the stale-guard stays
+   * correct even for bots that never write the field.
+   */
+  updated_at: external_exports.string().optional()
+});
+var SalvageStateSchema = external_exports.object({
+  status: external_exports.enum(["in_progress", "ready", "failed"]),
+  last_message: external_exports.string().optional().catch(void 0),
+  error: external_exports.string().optional().catch(void 0),
+  card_title: external_exports.string().optional().catch(void 0),
+  card_text: external_exports.string().optional().catch(void 0),
+  updated_at: external_exports.string().optional().catch(void 0)
 });
 function stateDirOf(worktreePath) {
   return path6.join(worktreePath, ".larkway");
@@ -119171,6 +119194,11 @@ async function readStateFileDetailed(worktreePath) {
     console.warn(`[stateFile] read ${file} failed:`, err);
     return { state: null, diagnostics: [] };
   }
+  let mtimeIso;
+  try {
+    mtimeIso = (await fs3.stat(file)).mtime.toISOString();
+  } catch {
+  }
   let parsed;
   try {
     parsed = JSON.parse(raw);
@@ -119195,18 +119223,39 @@ async function readStateFileDetailed(worktreePath) {
     }
   }
   const result = StateFileSchema.safeParse(parsed);
-  if (!result.success) {
-    console.warn(
-      `[stateFile] ${file} failed schema validation:`,
-      result.error.issues
-    );
-    return { state: null, diagnostics: [] };
-  }
-  const diagnostics = diagnoseStateFile(parsed, result.data);
-  for (const diagnostic of diagnostics) {
+  if (result.success) {
+    const state = withStampedUpdatedAt(result.data, mtimeIso);
+    const diagnostics = diagnoseStateFile(parsed, result.data);
+    for (const diagnostic of diagnostics) {
+      console.warn(`[stateFile] ${file}: ${diagnostic}`);
+    }
+    return { state, diagnostics };
+  }
+  const salvaged = SalvageStateSchema.safeParse(parsed);
+  if (salvaged.success) {
+    const droppedFields = summarizeRejectedTopFields(result.error);
+    const state = withStampedUpdatedAt(salvaged.data, mtimeIso);
+    const diagnostic = `state.json \u90E8\u5206\u5B57\u6BB5\u65E0\u6548\u5DF2\u5FFD\u7565\uFF0C\u4FDD\u7559 status/last_message\uFF08\u53D7\u5F71\u54CD\u5B57\u6BB5\uFF1A${droppedFields}\uFF09`;
     console.warn(`[stateFile] ${file}: ${diagnostic}`);
+    return { state, diagnostics: [diagnostic] };
+  }
+  console.warn(
+    `[stateFile] ${file} failed schema validation (unsalvageable):`,
+    result.error.issues
+  );
+  return { state: null, diagnostics: [] };
+}
+function withStampedUpdatedAt(state, mtimeIso) {
+  if (state.updated_at != null && state.updated_at !== "") return state;
+  return { ...state, updated_at: mtimeIso ?? (/* @__PURE__ */ new Date()).toISOString() };
+}
+function summarizeRejectedTopFields(error) {
+  const fields = /* @__PURE__ */ new Set();
+  for (const issue of error.issues) {
+    const top = issue.path[0];
+    fields.add(top === void 0 ? "(root)" : String(top));
   }
-  return { state: result.data, diagnostics };
+  return [...fields].join(", ") || "(unknown)";
 }
 function diagnoseStateFile(parsed, state) {
   if (parsed === null || typeof parsed !== "object") return [];
@@ -120952,7 +121001,9 @@ var BridgeHandler = class {
               });
             }
             const fallbackAnswer = trustedAnswerText.trim() || cardKitProgress?.answerText.trim() || "";
-            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 : "\u26A0\uFE0F \u672C\u8F6E\u6CA1\u6709\u62FF\u5230 agent \u7684\u65B0\u56DE\u590D(\u53EF\u80FD\u88AB\u4E2D\u65AD\u6216\u672A\u66F4\u65B0\u72B6\u6001),\u518D @ \u6211\u4E00\u6B21\u91CD\u8BD5\u3002");
+            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 noReportThisTurn = reportedState === null;
             const neutralTitle = noReportThisTurn && success && !failureReason ? "\u{1F4AC} \u5DF2\u56DE\u590D" : void 0;
             const baseCardPayload = {

package/package.json

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