From b6591c3f69c0c787f8d087217f1df4320c95a806 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Sat, 24 Jan 2026 02:54:22 +0000
Subject: [PATCH] fix: add log hint for agent failure (#1550) (thanks
 @sweepies)

---
 CHANGELOG.md                                        |  1 +
 ...es-error-cause-embedded-agent-throws.e2e.test.ts |  4 ++--
 src/auto-reply/reply/agent-runner-execution.ts      | 13 ++++++++-----
 3 files changed, 11 insertions(+), 7 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1929fd3be..d67df996d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -17,6 +17,7 @@ Docs: https://docs.clawd.bot
 - Voice wake: auto-save wake words on blur/submit across iOS/Android and align limits with macOS.
 - UI: keep the Control UI sidebar visible while scrolling long pages. (#1515) Thanks @pookNast.
 - Tailscale: retry serve/funnel with sudo only for permission errors and keep original failure details. (#1551) Thanks @sweepies.
+- Agents: add CLI log hint to "agent failed before reply" messages. (#1550) Thanks @sweepies.
 - Discord: limit autoThread mention bypass to bot-owned threads; keep ack reactions mention-gated. (#1511) Thanks @pvoo.
 - Gateway: accept null optional fields in exec approval requests. (#1511) Thanks @pvoo.
 - TUI: forward unknown slash commands (for example, `/context`) to the Gateway.
diff --git a/src/auto-reply/reply.triggers.trigger-handling.includes-error-cause-embedded-agent-throws.e2e.test.ts b/src/auto-reply/reply.triggers.trigger-handling.includes-error-cause-embedded-agent-throws.e2e.test.ts
index 9d8debd38..dfbfc7b5d 100644
--- a/src/auto-reply/reply.triggers.trigger-handling.includes-error-cause-embedded-agent-throws.e2e.test.ts
+++ b/src/auto-reply/reply.triggers.trigger-handling.includes-error-cause-embedded-agent-throws.e2e.test.ts
@@ -97,7 +97,7 @@ afterEach(() => {
 describe("trigger handling", () => {
   it("includes the error cause when the embedded agent throws", async () => {
     await withTempHome(async (home) => {
-      vi.mocked(runEmbeddedPiAgent).mockRejectedValue(new Error("sandbox is not defined"));
+      vi.mocked(runEmbeddedPiAgent).mockRejectedValue(new Error("sandbox is not defined."));
 
       const res = await getReplyFromConfig(
         {
@@ -111,7 +111,7 @@ describe("trigger handling", () => {
 
       const text = Array.isArray(res) ? res[0]?.text : res?.text;
       expect(text).toBe(
-        "⚠️ Agent failed before reply: sandbox is not defined. Check gateway logs for details.",
+        "⚠️ Agent failed before reply: sandbox is not defined.\nLogs: clawdbot logs --follow",
       );
       expect(runEmbeddedPiAgent).toHaveBeenCalledOnce();
     });
diff --git a/src/auto-reply/reply/agent-runner-execution.ts b/src/auto-reply/reply/agent-runner-execution.ts
index 92ee36dd0..ce653926d 100644
--- a/src/auto-reply/reply/agent-runner-execution.ts
+++ b/src/auto-reply/reply/agent-runner-execution.ts
@@ -507,14 +507,17 @@ export async function runAgentTurnWithFallback(params: {
       }
 
       defaultRuntime.error(`Embedded agent failed before reply: ${message}`);
+      const trimmedMessage = message.replace(/\.\s*$/, "");
+      const fallbackText = isContextOverflow
+        ? "⚠️ Context overflow — prompt too large for this model. Try a shorter message or a larger-context model."
+        : isRoleOrderingError
+          ? "⚠️ Message ordering conflict - please try again. If this persists, use /new to start a fresh session."
+          : `⚠️ Agent failed before reply: ${trimmedMessage}.\nLogs: clawdbot logs --follow`;
+
       return {
         kind: "final",
         payload: {
-          text: isContextOverflow
-            ? "⚠️ Context overflow — prompt too large for this model. Try a shorter message or a larger-context model."
-            : isRoleOrderingError
-              ? "⚠️ Message ordering conflict - please try again. If this persists, use /new to start a fresh session."
-              : `⚠️ Agent failed before reply: ${message}\nCheck gateway logs for details.`,
+          text: fallbackText,
         },
       };
     }