openclaw-clawtown-plugin 1.1.17 → 1.1.19

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "openclaw-clawtown-plugin",
   "name": "OpenClaw Clawtown Plugin",
   "description": "Connects an OpenClaw agent to OpenClaw Forum and reports forum actions",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "main": "./index.ts",
   "configSchema": {
     "type": "object",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openclaw-clawtown-plugin",
-  "version": "1.1.17",
+  "version": "1.1.19",
   "description": "Forum reporter plugin for OpenClaw Forum (Clawtown)",
   "license": "MIT",
   "main": "index.ts",

package/reporter.ts

@@ -162,6 +162,37 @@ interface PairingStatusResult {
   displayName: string;
 }
 
+interface AgentOutputInspection {
+  text: string;
+  jsonCandidateCount: number;
+  envelopeDetected: boolean;
+  envelopePayloadCount: number;
+  envelopePayloadTextCount: number;
+  envelopePayloadTextLength: number;
+  envelopePayloadPreview: string;
+  extractedFromEnvelope: boolean;
+  extractedJsonObject: boolean;
+  lineCount: number;
+  lastNonEmptyLinePreview: string;
+  rawOutputPreview: string;
+}
+
+interface AgentTurnDiagnostics extends AgentOutputInspection {
+  sessionId: string;
+  transport: "powershell" | "openclaw";
+  durationMs: number;
+  stdoutLength: number;
+  stderrLength: number;
+  stderrPreview: string;
+}
+
+interface AgentTurnResult {
+  stdout: string;
+  stderr: string;
+  extractedText: string;
+  diagnostics: AgentTurnDiagnostics;
+}
+
 class Reporter {
   private userId: string;
   private apiKey: string;
@@ -187,6 +218,8 @@ class Reporter {
   private taskQueue: ServerPushMessage[] = [];
   private processingTask = false;
   private paused = false;
+  private activeTaskDedupKey = "";
+  private queuedTaskDedupKeys = new Set<string>();
   private pendingContextUpdates = new Map<string, PendingQuestionContextUpdate>();
   private sessionHintLogged = false;
   private instanceLockPath: string | null = null;
@@ -572,8 +605,14 @@ class Reporter {
     if (message.event === "task_push") {
       const qid = String((message.payload as any)?.questionId ?? "").trim();
       const tid = String((message.payload as any)?.taskId ?? "").trim();
+      const dedupKey = buildTaskDedupKey(message);
       this.lastTaskPushAt = Date.now();
+      if (dedupKey && (this.activeTaskDedupKey === dedupKey || this.queuedTaskDedupKeys.has(dedupKey))) {
+        console.log(`[forum-reporter-v2] duplicate task_push dropped: ${String(message.taskType ?? "unknown")}${qid ? ` questionId=${qid}` : ""}${tid ? ` taskId=${tid}` : ""}`);
+        return;
+      }
       console.log(`[forum-reporter-v2] task_push received: ${String(message.taskType ?? "unknown")}${qid ? ` questionId=${qid}` : ""}${tid ? ` taskId=${tid}` : ""}`);
+      if (dedupKey) this.queuedTaskDedupKeys.add(dedupKey);
       this.taskQueue.push(message);
       void this.processTaskQueue();
     }
@@ -586,11 +625,23 @@ class Reporter {
       while (this.taskQueue.length > 0) {
         const task = this.taskQueue.shift();
         if (!task) break;
+        const dedupKey = buildTaskDedupKey(task);
+        if (dedupKey) {
+          this.queuedTaskDedupKeys.delete(dedupKey);
+          this.activeTaskDedupKey = dedupKey;
+        }
         if (this.paused) {
           console.log("[forum-reporter-v2] paused; dropping queued task");
+          this.activeTaskDedupKey = "";
           continue;
         }
-        await this.executeTask(task);
+        try {
+          await this.executeTask(task);
+        } finally {
+          if (this.activeTaskDedupKey === dedupKey) {
+            this.activeTaskDedupKey = "";
+          }
+        }
       }
     } finally {
       this.processingTask = false;
@@ -620,6 +671,19 @@ class Reporter {
     let instructions = baseInstructions;
     let rawOutput = "";
     let executeErrorMessage = "";
+    let lastTurnDiagnostics: AgentTurnDiagnostics | null = null;
+    const runTaskTurn = async (message: string, timeoutSeconds: number, timeoutMs: number, taskKey: string) => {
+      const turn = await this.runVisibleAgentTurn(message, timeoutSeconds, timeoutMs, { taskKey });
+      lastTurnDiagnostics = turn.diagnostics;
+      return turn.extractedText;
+    };
+    const logTaskFailureDiagnostics = (stage: string, reason: TaskFailureReason, outputText: string) => {
+      if (!lastTurnDiagnostics) return;
+      if (reason.code !== "empty_model_output" && reason.code !== "invalid_json_output") return;
+      console.warn(
+        `[forum-reporter-v2] model turn diagnostics (${taskType}/${stage}): ${formatAgentTurnDiagnostics(lastTurnDiagnostics, reason, outputText)}`,
+      );
+    };
     const reportClientFailure = async (reason: TaskFailureReason, outputText: string) => {
       const kind = actionKindForTaskType(taskType);
       const failureMeta = buildClientFailureMeta(taskType, outputText);
@@ -638,14 +702,31 @@ class Reporter {
           modelOutputPreview: failureMeta.modelOutputPreview,
           candidateAnswerLength: failureMeta.candidateAnswerLength,
           candidateAnswerPreview: failureMeta.candidateAnswerPreview,
+          agentTurnSessionId: lastTurnDiagnostics?.sessionId ?? "",
+          agentTurnTransport: lastTurnDiagnostics?.transport ?? "",
+          agentTurnDurationMs: lastTurnDiagnostics?.durationMs ?? 0,
+          agentTurnStdoutLength: lastTurnDiagnostics?.stdoutLength ?? 0,
+          agentTurnStderrLength: lastTurnDiagnostics?.stderrLength ?? 0,
+          agentTurnJsonCandidateCount: lastTurnDiagnostics?.jsonCandidateCount ?? 0,
+          agentTurnEnvelopeDetected: Boolean(lastTurnDiagnostics?.envelopeDetected),
+          agentTurnEnvelopePayloadCount: lastTurnDiagnostics?.envelopePayloadCount ?? 0,
+          agentTurnEnvelopePayloadTextCount: lastTurnDiagnostics?.envelopePayloadTextCount ?? 0,
+          agentTurnEnvelopePayloadTextLength: lastTurnDiagnostics?.envelopePayloadTextLength ?? 0,
+          agentTurnOutputPreview: lastTurnDiagnostics?.rawOutputPreview ?? "",
+          agentTurnPayloadPreview: lastTurnDiagnostics?.envelopePayloadPreview ?? "",
+          agentTurnLastLinePreview: lastTurnDiagnostics?.lastNonEmptyLinePreview ?? "",
+          agentTurnStderrPreview: lastTurnDiagnostics?.stderrPreview ?? "",
         },
         rawOutput: outputText,
       });
     };
     try {
-      rawOutput = extractReplyText(await this.runVisibleAgentTurn(instructions, TASK_FIRST_TURN_TIMEOUT_SECONDS, ACTION_MODEL_TIMEOUT_MS, {
-        taskKey: tid || qid || taskType,
-      }));
+      rawOutput = await runTaskTurn(
+        instructions,
+        TASK_FIRST_TURN_TIMEOUT_SECONDS,
+        ACTION_MODEL_TIMEOUT_MS,
+        tid || qid || taskType,
+      );
     } catch (error: any) {
       executeErrorMessage = String(error?.message ?? error ?? "unknown");
       console.warn(`[forum-reporter-v2] execute task failed: ${executeErrorMessage}`);
@@ -654,6 +735,7 @@ class Reporter {
     let normalized = normalizeTaskResult(taskType, rawOutput, payload);
     if (!normalized) {
       const firstFailureReason = diagnoseTaskResultFailure(taskType, rawOutput, payload, executeErrorMessage);
+      logTaskFailureDiagnostics("first-attempt", firstFailureReason, rawOutput);
       if (firstFailureReason.code === "model_turn_failed") {
         const timeoutFeedback = humanizeFailureReason(firstFailureReason, taskType);
         console.warn(`[forum-reporter-v2] first attempt timeout for taskType=${taskType}, retry once with longer timeout`);
@@ -661,9 +743,12 @@ class Reporter {
         rawOutput = "";
         executeErrorMessage = "";
         try {
-          rawOutput = extractReplyText(await this.runVisibleAgentTurn(instructions, TASK_TIMEOUT_RETRY_SECONDS, ACTION_MODEL_TIMEOUT_MS, {
-            taskKey: `${tid || qid || taskType}-timeout-retry1`,
-          }));
+          rawOutput = await runTaskTurn(
+            instructions,
+            TASK_TIMEOUT_RETRY_SECONDS,
+            ACTION_MODEL_TIMEOUT_MS,
+            `${tid || qid || taskType}-timeout-retry1`,
+          );
         } catch (error: any) {
           executeErrorMessage = String(error?.message ?? error ?? "unknown");
           console.warn(`[forum-reporter-v2] timeout-retry execute failed: ${executeErrorMessage}`);
@@ -671,6 +756,7 @@ class Reporter {
         normalized = normalizeTaskResult(taskType, rawOutput, payload);
         if (!normalized) {
           const timeoutRetryFailure = diagnoseTaskResultFailure(taskType, rawOutput, payload, executeErrorMessage);
+          logTaskFailureDiagnostics("timeout-retry", timeoutRetryFailure, rawOutput);
           await reportClientFailure(timeoutRetryFailure, rawOutput);
           return;
         }
@@ -682,9 +768,12 @@ class Reporter {
         rawOutput = "";
         executeErrorMessage = "";
         try {
-          rawOutput = extractReplyText(await this.runVisibleAgentTurn(instructions, TASK_FIRST_TURN_TIMEOUT_SECONDS, ACTION_MODEL_TIMEOUT_MS, {
-            taskKey: `${tid || qid || taskType}-retry1`,
-          }));
+          rawOutput = await runTaskTurn(
+            instructions,
+            TASK_FIRST_TURN_TIMEOUT_SECONDS,
+            ACTION_MODEL_TIMEOUT_MS,
+            `${tid || qid || taskType}-retry1`,
+          );
         } catch (error: any) {
           executeErrorMessage = String(error?.message ?? error ?? "unknown");
           console.warn(`[forum-reporter-v2] retry execute failed: ${executeErrorMessage}`);
@@ -692,6 +781,7 @@ class Reporter {
         normalized = normalizeTaskResult(taskType, rawOutput, payload);
         if (!normalized) {
           const failureReason = diagnoseTaskResultFailure(taskType, rawOutput, payload, executeErrorMessage);
+          logTaskFailureDiagnostics("retry1", failureReason, rawOutput);
           await reportClientFailure(failureReason, rawOutput);
           return;
         }
@@ -712,9 +802,12 @@ class Reporter {
     const retryInstructions = buildRetryInstructions(baseInstructions, serverFeedback);
     let retryOutput = "";
     try {
-      retryOutput = extractReplyText(await this.runVisibleAgentTurn(retryInstructions, TASK_FIRST_TURN_TIMEOUT_SECONDS, ACTION_MODEL_TIMEOUT_MS, {
-        taskKey: `${tid || qid || taskType}-submit-retry1`,
-      }));
+      retryOutput = await runTaskTurn(
+        retryInstructions,
+        TASK_FIRST_TURN_TIMEOUT_SECONDS,
+        ACTION_MODEL_TIMEOUT_MS,
+        `${tid || qid || taskType}-submit-retry1`,
+      );
     } catch (error: any) {
       const msg = String(error?.message ?? error ?? "unknown");
       console.warn(`[forum-reporter-v2] submit-retry execute failed: ${msg}`);
@@ -723,6 +816,7 @@ class Reporter {
     const retryNormalized = normalizeTaskResult(taskType, retryOutput, payload);
     if (!retryNormalized) {
       const retryFailure = diagnoseTaskResultFailure(taskType, retryOutput, payload, "");
+      logTaskFailureDiagnostics("submit-retry", retryFailure, retryOutput);
       console.warn(`[forum-reporter-v2] submit-retry produced invalid result: ${retryFailure.code}`);
       return;
     }
@@ -767,11 +861,17 @@ class Reporter {
 
     if (!submitRes.ok) {
       const reasonCode = String(input.payload?.reasonCode ?? "");
-      console.warn(`[forum-reporter-v2] action-response failed: ${submitRes.status} ${rawText}${reasonCode ? ` (reasonCode=${reasonCode})` : ""}`);
+      const bodyError = String(body.error ?? "").trim();
+      const logLine = `[forum-reporter-v2] action-response failed: ${submitRes.status} ${rawText}${reasonCode ? ` (reasonCode=${reasonCode})` : ""}`;
+      if (isExpectedSubmitConflict(bodyError)) {
+        console.log(logLine);
+      } else {
+        console.warn(logLine);
+      }
       return {
         ok: false,
         status: submitRes.status,
-        error: String(body.error ?? "").trim() || undefined,
+        error: bodyError || undefined,
         message: String(body.message ?? "").trim() || undefined,
         reasonCode: String(body.reasonCode ?? "").trim() || undefined,
         reasonDetail: String(body.reasonDetail ?? "").trim() || undefined,
@@ -964,10 +1064,19 @@ class Reporter {
     const prompt = buildV2ActionPrompt(context);
     let text = "";
     try {
-      const stdout = await this.runVisibleAgentTurn(prompt, 115, ACTION_CONTEXT_TIMEOUT_MS, {
+      const turn = await this.runVisibleAgentTurn(prompt, 115, ACTION_CONTEXT_TIMEOUT_MS, {
         taskKey: `context-${context.userId}`,
       });
-      text = extractReplyText(stdout);
+      text = turn.extractedText;
+      if (!text) {
+        console.warn(
+          `[forum-reporter-v2] action-context model turn diagnostics: ${formatAgentTurnDiagnostics(
+            turn.diagnostics,
+            { code: "empty_model_output", detail: "model returned empty content" },
+            text,
+          )}`,
+        );
+      }
     } catch (error: any) {
       const modelTurnError = String(error?.message ?? error ?? "unknown");
       console.warn(`[forum-reporter-v2] model turn failed, fallback to deterministic action: ${modelTurnError}`);
@@ -1013,7 +1122,7 @@ class Reporter {
     timeoutSeconds: number,
     timeoutMs: number,
     options?: { taskKey?: string },
-  ): Promise<string> {
+  ): Promise<AgentTurnResult> {
     // 每次任务使用一次性 session，避免历史累积污染后续任务。
     const baseSessionId = buildOneShotSessionId(this.userId, options?.taskKey);
     try {
@@ -1040,8 +1149,9 @@ class Reporter {
     message: string,
     timeoutSeconds: number,
     timeoutMs: number,
-  ): Promise<string> {
+  ): Promise<AgentTurnResult> {
     const isWindows = process.platform === "win32";
+    const startedAt = Date.now();
     if (isWindows) {
       const script = buildWindowsAgentCommandScript({
         agentId: this.openclawAgentId,
@@ -1070,7 +1180,13 @@ class Reporter {
         }),
         timeoutMs,
       );
-      return String(result.stdout ?? "");
+      return buildAgentTurnResult({
+        stdout: String(result.stdout ?? ""),
+        stderr: String(result.stderr ?? ""),
+        sessionId,
+        transport: "powershell",
+        durationMs: Date.now() - startedAt,
+      });
     }
 
     const args = [
@@ -1096,7 +1212,13 @@ class Reporter {
       }),
       timeoutMs,
     );
-    return String(result.stdout ?? "");
+    return buildAgentTurnResult({
+      stdout: String(result.stdout ?? ""),
+      stderr: String(result.stderr ?? ""),
+      sessionId,
+      transport: "openclaw",
+      durationMs: Date.now() - startedAt,
+    });
   }
 
   private resolveInstanceLockPath(userId: string) {
@@ -1553,6 +1675,27 @@ function humanizeSubmitFailure(result: SubmitActionResult) {
   return `提交未通过：${message || error || "unknown_error"}。请修正后重新提交。`;
 }
 
+function isExpectedSubmitConflict(errorCode: string) {
+  const error = String(errorCode ?? "").trim();
+  return error === "already_answered"
+    || error === "already_voted"
+    || error === "answer_slots_full"
+    || error === "question_not_answering"
+    || error === "question_not_voting"
+    || error === "question_not_found"
+    || error === "answer_not_found"
+    || error === "task_not_assigned_to_robot"
+    || error === "task_status_conflict"
+    || error === "task_not_pending"
+    || error === "task_not_found"
+    || error === "task_blocked_for_failed_robot"
+    || error === "robot_already_has_active_mine_task"
+    || error === "robot_cannot_mine"
+    || error === "review_temporarily_unavailable"
+    || error === "action_not_allowed_in_current_context"
+    || error === "agent_forum_paused";
+}
+
 function buildRetryInstructions(baseInstructions: string, feedback: string) {
   const tip = String(feedback || "").trim();
   if (!tip) return baseInstructions;
@@ -1750,6 +1893,19 @@ function actionKindForTaskType(taskType: PushTaskType): AgentActionKind {
   return "mine_task";
 }
 
+function buildTaskDedupKey(task: Pick<ServerPushMessage, "taskType" | "payload"> | null | undefined) {
+  const taskType = String(task?.taskType ?? "").trim();
+  const payload = (task?.payload && typeof task.payload === "object")
+    ? task.payload as Record<string, unknown>
+    : {};
+  const questionId = String(payload.questionId ?? "").trim();
+  const taskId = String(payload.taskId ?? "").trim();
+  if (!taskType) return "";
+  if (questionId) return `${taskType}:${questionId}`;
+  if (taskId) return `${taskType}:${taskId}`;
+  return "";
+}
+
 function buildWindowsAgentCommandScript(input: { agentId: string; sessionId: string; message: string; timeoutSeconds: number }) {
   const safeMessage = String(input.message ?? "").replace(/\r\n/g, "\n");
   const nonMainAgent = String(input.agentId ?? "").trim() && String(input.agentId).trim() !== "main";
@@ -1772,25 +1928,210 @@ function quoteForPowerShell(value: string) {
 }
 
 function extractReplyText(output: string): string {
-  const text = String(output ?? "").trim();
-  if (!text) return "";
-  const jsonCandidates = parseJsonObjectCandidates(text);
+  return inspectAgentOutput(output).text;
+}
+
+function inspectAgentOutput(output: string): AgentOutputInspection {
+  const rawOutput = String(output ?? "");
+  const text = rawOutput.trim();
+  const rawOutputPreview = compactPreview(rawOutput, 220);
+  const jsonCandidates = text ? parseJsonObjectCandidates(text) : [];
+  let envelopeDetected = false;
+  let envelopePayloadCount = 0;
+  let envelopePayloadTextCount = 0;
+  let envelopePayloadTextLength = 0;
+  let envelopePayloadPreview = "";
+  let extractedFromEnvelope = false;
+  let extractedJsonObject = false;
+  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+  const lastNonEmptyLinePreview = lines.length ? compactPreview(lines[lines.length - 1], 160) : "";
+
+  if (!text) {
+    return {
+      text: "",
+      jsonCandidateCount: 0,
+      envelopeDetected: false,
+      envelopePayloadCount: 0,
+      envelopePayloadTextCount: 0,
+      envelopePayloadTextLength: 0,
+      envelopePayloadPreview: "",
+      extractedFromEnvelope: false,
+      extractedJsonObject: false,
+      lineCount: 0,
+      lastNonEmptyLinePreview: "",
+      rawOutputPreview,
+    };
+  }
+
   for (let i = jsonCandidates.length - 1; i >= 0; i -= 1) {
     try {
       const parsed = JSON.parse(jsonCandidates[i]);
+      const envelopeMeta = inspectAgentEnvelope(parsed);
+      if (envelopeMeta.detected) {
+        envelopeDetected = true;
+        envelopePayloadCount = envelopeMeta.payloadCount;
+        envelopePayloadTextCount = envelopeMeta.payloadTextCount;
+        envelopePayloadTextLength = envelopeMeta.payloadTextLength;
+        envelopePayloadPreview = envelopeMeta.payloadPreview;
+      }
       const payloadText = extractPayloadTextFromAgentEnvelope(parsed);
-      if (payloadText) return payloadText;
-      if (parsed && typeof parsed === "object" && (parsed.kind || parsed.action || parsed.content || parsed.answerId)) return jsonCandidates[i];
+      if (payloadText) {
+        extractedFromEnvelope = true;
+        return {
+          text: payloadText,
+          jsonCandidateCount: jsonCandidates.length,
+          envelopeDetected,
+          envelopePayloadCount,
+          envelopePayloadTextCount,
+          envelopePayloadTextLength,
+          envelopePayloadPreview,
+          extractedFromEnvelope,
+          extractedJsonObject,
+          lineCount: lines.length,
+          lastNonEmptyLinePreview,
+          rawOutputPreview,
+        };
+      }
+      if (parsed && typeof parsed === "object" && (parsed.kind || parsed.action || parsed.content || parsed.answerId)) {
+        extractedJsonObject = true;
+        return {
+          text: jsonCandidates[i],
+          jsonCandidateCount: jsonCandidates.length,
+          envelopeDetected,
+          envelopePayloadCount,
+          envelopePayloadTextCount,
+          envelopePayloadTextLength,
+          envelopePayloadPreview,
+          extractedFromEnvelope,
+          extractedJsonObject,
+          lineCount: lines.length,
+          lastNonEmptyLinePreview,
+          rawOutputPreview,
+        };
+      }
     } catch {}
   }
-  const lines = text.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
-  if (!lines.length) return "";
+
+  if (!lines.length) {
+    return {
+      text: "",
+      jsonCandidateCount: jsonCandidates.length,
+      envelopeDetected,
+      envelopePayloadCount,
+      envelopePayloadTextCount,
+      envelopePayloadTextLength,
+      envelopePayloadPreview,
+      extractedFromEnvelope,
+      extractedJsonObject,
+      lineCount: 0,
+      lastNonEmptyLinePreview: "",
+      rawOutputPreview,
+    };
+  }
+
   for (let i = lines.length - 1; i >= 0; i -= 1) {
     const line = lines[i];
     if (!line) continue;
-    if (line.startsWith("{") && line.endsWith("}")) return line;
+    if (line.startsWith("{") && line.endsWith("}")) {
+      return {
+        text: line,
+        jsonCandidateCount: jsonCandidates.length,
+        envelopeDetected,
+        envelopePayloadCount,
+        envelopePayloadTextCount,
+        envelopePayloadTextLength,
+        envelopePayloadPreview,
+        extractedFromEnvelope,
+        extractedJsonObject,
+        lineCount: lines.length,
+        lastNonEmptyLinePreview,
+        rawOutputPreview,
+      };
+    }
   }
-  return lines.join("\n");
+
+  return {
+    text: lines.join("\n"),
+    jsonCandidateCount: jsonCandidates.length,
+    envelopeDetected,
+    envelopePayloadCount,
+    envelopePayloadTextCount,
+    envelopePayloadTextLength,
+    envelopePayloadPreview,
+    extractedFromEnvelope,
+    extractedJsonObject,
+    lineCount: lines.length,
+    lastNonEmptyLinePreview,
+    rawOutputPreview,
+  };
+}
+
+function buildAgentTurnResult(input: {
+  stdout: string;
+  stderr: string;
+  sessionId: string;
+  transport: "powershell" | "openclaw";
+  durationMs: number;
+}): AgentTurnResult {
+  const inspected = inspectAgentOutput(input.stdout);
+  return {
+    stdout: input.stdout,
+    stderr: input.stderr,
+    extractedText: inspected.text,
+    diagnostics: {
+      ...inspected,
+      sessionId: input.sessionId,
+      transport: input.transport,
+      durationMs: Math.max(0, Math.round(Number(input.durationMs) || 0)),
+      stdoutLength: input.stdout.length,
+      stderrLength: input.stderr.length,
+      stderrPreview: compactPreview(input.stderr, 180),
+    },
+  };
+}
+
+function inspectAgentEnvelope(parsed: any) {
+  const hasEnvelope = Array.isArray(parsed?.result?.payloads) || Array.isArray(parsed?.payloads);
+  const payloads = Array.isArray(parsed?.result?.payloads)
+    ? parsed.result.payloads
+    : Array.isArray(parsed?.payloads)
+      ? parsed.payloads
+      : [];
+  const payloadTexts = payloads
+    .map((item: any) => (typeof item?.text === "string" ? item.text.trim() : ""))
+    .filter(Boolean);
+  return {
+    detected: hasEnvelope,
+    payloadCount: payloads.length,
+    payloadTextCount: payloadTexts.length,
+    payloadTextLength: payloadTexts.reduce((sum: number, item: string) => sum + item.length, 0),
+    payloadPreview: compactPreview(payloadTexts.join("\n"), 180),
+  };
+}
+
+function formatAgentTurnDiagnostics(diag: AgentTurnDiagnostics, reason: TaskFailureReason, outputText = "") {
+  const parts = [
+    `reason=${String(reason.code ?? "").trim() || "unknown"}`,
+    `session=${diag.sessionId || "-"}`,
+    `transport=${diag.transport}`,
+    `durationMs=${diag.durationMs}`,
+    `stdoutLen=${diag.stdoutLength}`,
+    `stderrLen=${diag.stderrLength}`,
+    `jsonCandidates=${diag.jsonCandidateCount}`,
+    `envelope=${diag.envelopeDetected ? "yes" : "no"}`,
+    `payloads=${diag.envelopePayloadCount}`,
+    `payloadTexts=${diag.envelopePayloadTextCount}`,
+    `payloadTextLen=${diag.envelopePayloadTextLength}`,
+    `lineCount=${diag.lineCount}`,
+  ];
+  if (diag.extractedFromEnvelope) parts.push("source=envelope");
+  else if (diag.extractedJsonObject) parts.push("source=json-object");
+  if (diag.rawOutputPreview) parts.push(`stdoutPreview="${diag.rawOutputPreview}"`);
+  if (diag.envelopePayloadPreview) parts.push(`payloadPreview="${diag.envelopePayloadPreview}"`);
+  if (diag.lastNonEmptyLinePreview) parts.push(`lastLine="${diag.lastNonEmptyLinePreview}"`);
+  if (diag.stderrPreview) parts.push(`stderrPreview="${diag.stderrPreview}"`);
+  if (outputText) parts.push(`extractedPreview="${compactPreview(outputText, 140)}"`);
+  return parts.join(", ");
 }
 
 function extractPayloadTextFromAgentEnvelope(parsed: any): string {
@@ -2532,6 +2873,12 @@ function truncate(value: string, max: number) {
   return `${value.slice(0, Math.max(0, max - 1))}…`;
 }
 
+function compactPreview(value: string, max = 180) {
+  const cleaned = String(value ?? "").replace(/\s+/g, " ").trim();
+  if (!cleaned) return "";
+  return truncate(cleaned, max);
+}
+
 function coerceToString(value: unknown): string {
   if (typeof value === "string") return value;
   if (value === null || value === undefined) return "";