From af0cc3feadbc37451f3d39ac21e1a41b08a89bab Mon Sep 17 00:00:00 2001
From: kris <krisoso.com@gmail.com>
Date: Sun, 5 Apr 2026 05:19:18 +0800
Subject: [PATCH] refactor: clarify thread execution failure notices

---
 src/lib/boss-data.ts                          | 28 +++++++++++++++++--
 tests/dispatch-execution-result.test.ts       |  2 +-
 tests/single-thread-message-execution.test.ts |  2 +-
 3 files changed, 28 insertions(+), 4 deletions(-)

diff --git a/src/lib/boss-data.ts b/src/lib/boss-data.ts
index 0d9c9bb..cf89e33 100644
--- a/src/lib/boss-data.ts
+++ b/src/lib/boss-data.ts
@@ -6051,7 +6051,7 @@ function appendDispatchExecutionResultInState(
       sender: "ops",
       senderLabel: "主 Agent Relay",
       body: payload.failureReason?.trim()
-        ? `${threadTitle} 执行失败：${payload.failureReason.trim()}`
+        ? `${threadTitle} 执行失败：${buildFriendlyThreadExecutionError(payload.failureReason)}`
         : `${threadTitle} 执行失败，请稍后重试。`,
       kind: "text",
     });
@@ -6434,7 +6434,7 @@ export async function completeMasterAgentTask(payload: {
             ? `主 Agent Relay · ${task.accountLabel}`
             : "主 Agent Relay",
         body: isThreadConversationReply
-          ? `${task.targetThreadDisplayName ?? "当前线程"} 执行失败：${task.errorMessage ?? "UNKNOWN_ERROR"}`
+          ? `${task.targetThreadDisplayName ?? "当前线程"} 执行失败：${buildFriendlyThreadExecutionError(task.errorMessage)}`
           : `Master Codex Node 执行失败：${task.errorMessage ?? "UNKNOWN_ERROR"}`,
         kind: "text",
       });
@@ -7605,6 +7605,30 @@ function buildProjectUnderstandingCollaborationNotice(projectName: string, snaps
     .join("\n");
 }
 
+function buildFriendlyThreadExecutionError(errorMessage?: string) {
+  const message = errorMessage?.trim();
+  if (!message) {
+    return "线程执行失败，请稍后重试。";
+  }
+  if (message.includes("LOCAL_AGENT_CODEX_THREAD_BINDING_MISSING")) {
+    return "线程绑定缺失，请重新导入或重新绑定该线程后再试。";
+  }
+  if (message.includes("LOCAL_AGENT_CODEX_THREAD_BINDING_STALE")) {
+    return "线程绑定已失效，请重新导入或重新绑定该线程后再试。";
+  }
+  if (
+    message.includes("LOCAL_AGENT_CODEX_THREAD_BINDING_MISMATCH") ||
+    message.includes("LOCAL_AGENT_CODEX_WORKDIR_INVALID") ||
+    message.includes("THREAD_ENVIRONMENT_INVALID")
+  ) {
+    return "线程环境异常，请重新绑定到正确项目或工作目录后再试。";
+  }
+  if (message.includes("LOCAL_AGENT_CODEX_THREAD_READ_ONLY")) {
+    return "线程当前处于只读环境，无法继续执行，请切换到可写线程后再试。";
+  }
+  return message;
+}
+
 function shouldQueueProjectUnderstandingSync(
   project: Project,
   observedActivityAt: string,
diff --git a/tests/dispatch-execution-result.test.ts b/tests/dispatch-execution-result.test.ts
index a7d02b4..d9d2779 100644
--- a/tests/dispatch-execution-result.test.ts
+++ b/tests/dispatch-execution-result.test.ts
@@ -328,7 +328,7 @@ test("POST /api/v1/master-agent/tasks/[taskId]/complete blocks leaked thread env
   assert.equal(leakedReply, undefined);
 
   const opsNotice = groupMessages.find((message) =>
-    message.body.includes("线程返回了内部环境提示，已拦截"),
+    message.body.includes("线程环境异常，请重新绑定到正确项目或工作目录后再试。"),
   );
   assert.ok(opsNotice, "expected a system notice instead of raw leaked diagnostics");
 });
diff --git a/tests/single-thread-message-execution.test.ts b/tests/single-thread-message-execution.test.ts
index 1f1d4a6..aa6069d 100644
--- a/tests/single-thread-message-execution.test.ts
+++ b/tests/single-thread-message-execution.test.ts
@@ -255,7 +255,7 @@ test("POST /api/v1/master-agent/tasks/[taskId]/complete blocks leaked thread env
   assert.equal(leakedReply, undefined);
 
   const opsNotice = updatedProject?.messages.find((message) =>
-    message.body.includes("线程返回了内部环境提示，已拦截"),
+    message.body.includes("线程环境异常，请重新绑定到正确项目或工作目录后再试。"),
   );
   assert.ok(opsNotice, "expected a user-facing system notice instead of raw environment diagnostics");
 });