Gate turn memory diagnostics behind debug mode

Route turn-memory reflection success and failure diagnostics through an explicit AUTOHAND_DEBUG check before writing to the live debug line surface.

Co-authored-by: Autohand Evolve <code-noreply@autohand.ai>

Author: igorcosta

src/core/agent.ts

@@ -12,7 +12,7 @@ import type { LLMProvider } from '../providers/LLMProvider.js';
 import { safeEmitKeypressEvents } from '../ui/inputPrompt.js';
 
 import { safeSetRawMode } from '../ui/rawMode.js';
-import { writeAutohandDebugLine } from '../utils/debugLog.js';
+import { isAutohandDebugEnabled } from '../utils/debugLog.js';
 import type { UIManager } from '../ui/UIManager.js';
 import { GitIgnoreParser } from '../utils/gitIgnore.js';
 import { ConversationManager } from './conversationManager.js';
@@ -580,10 +580,7 @@ export class AutohandAgent {
     this.turnMemoryReflectionInFlight = this.runQueuedTurnMemoryReflection()
       .catch((error: unknown) => {
         const message = error instanceof Error ? error.message : String(error);
-        writeAutohandDebugLine(
-          `[memory] turn reflection failed: ${message}`,
-          this.writeDebugLine.bind(this),
-        );
+        this.writeTurnMemoryDebugLine(`[memory] turn reflection failed: ${message}`);
       })
       .finally(() => {
         this.turnMemoryReflectionInFlight = null;
@@ -625,12 +622,19 @@ export class AutohandAgent {
     }
 
     this.conversation.addSystemNote(formatTurnMemoryUpdate(saved), '[Auto Memory Update]');
-    writeAutohandDebugLine(
+    this.writeTurnMemoryDebugLine(
       `[memory] turn reflection saved ${saved.length} ${saved.length === 1 ? 'memory' : 'memories'}`,
-      this.writeDebugLine.bind(this),
     );
   }
 
+  private writeTurnMemoryDebugLine(message: string): void {
+    if (!isAutohandDebugEnabled()) {
+      return;
+    }
+
+    this.writeDebugLine(message);
+  }
+
   private async flushTurnMemoryReflection(timeoutMs = 1500): Promise<void> {
     if (!this.turnMemoryReflectionInFlight) {
       return;

tests/core/agent/TurnMemoryReflection.test.ts

@@ -3,9 +3,19 @@
  * Copyright 2025 Autohand AI LLC
  * SPDX-License-Identifier: Apache-2.0
  */
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 import { AutohandAgent } from '../../../src/core/agent.js';
 
+const originalDebug = process.env.AUTOHAND_DEBUG;
+
+afterEach(() => {
+  if (originalDebug === undefined) {
+    delete process.env.AUTOHAND_DEBUG;
+  } else {
+    process.env.AUTOHAND_DEBUG = originalDebug;
+  }
+});
+
 function createAgentHarness() {
   const agent = Object.create(AutohandAgent.prototype) as any;
   const memoryManager = {
@@ -75,13 +85,35 @@ describe('turn memory reflection', () => {
 
   it('does not write a success notice into the live terminal after background reflection', async () => {
     const { agent } = createAgentHarness();
+    delete process.env.AUTOHAND_DEBUG;
+
+    agent.scheduleTurnMemoryReflection(true);
+    await agent.turnMemoryReflectionInFlight;
+
+    expect(agent.writeDebugLine).not.toHaveBeenCalled();
+  });
+
+  it('does not write a failure notice into the live terminal unless debug logging is enabled', async () => {
+    const { agent, llm } = createAgentHarness();
+    llm.complete.mockRejectedValueOnce(new Error('memory unavailable'));
+    delete process.env.AUTOHAND_DEBUG;
 
     agent.scheduleTurnMemoryReflection(true);
     await agent.turnMemoryReflectionInFlight;
 
     expect(agent.writeDebugLine).not.toHaveBeenCalled();
   });
 
+  it('writes turn memory diagnostics when AUTOHAND_DEBUG is enabled', async () => {
+    const { agent } = createAgentHarness();
+    process.env.AUTOHAND_DEBUG = '1';
+
+    agent.scheduleTurnMemoryReflection(true);
+    await agent.turnMemoryReflectionInFlight;
+
+    expect(agent.writeDebugLine).toHaveBeenCalledWith('[memory] turn reflection saved 1 memory');
+  });
+
   it('does not run when auto-memory is disabled', () => {
     const { agent, llm } = createAgentHarness();
     agent.runtime.config.agent.autoMemory = false;