mstro-app 0.3.8 → 0.3.9

package/server/cli/headless/claude-invoker.ts

@@ -9,6 +9,7 @@
 
 import { type ChildProcess, spawn } from 'node:child_process';
 import { sanitizeEnvForSandbox } from '../../services/sandbox-utils.js';
+import { herror, hlog } from './headless-logger.js';
 import { generateMcpConfig } from './mcp-config.js';
 import { detectErrorInStderr, } from './output-utils.js';
 import { buildMultimodalMessage } from './prompt-utils.js';
@@ -115,7 +116,7 @@ async function runStallAssessment(
         );
       }
       if (config.verbose) {
-        console.log(`[STALL] Extended by ${Math.round(verdict.extensionMs / 60_000)} min: ${verdict.reason}`);
+        hlog(`[STALL] Extended by ${Math.round(verdict.extensionMs / 60_000)} min: ${verdict.reason}`);
       }
       return { extensionsGranted: newExtensions, currentKillDeadline: now + verdict.extensionMs };
     }
@@ -123,11 +124,11 @@ async function runStallAssessment(
       `\n[[MSTRO_STALL_CONFIRMED]] Assessment: process likely stalled. ${verdict.reason}.\n`
     );
     if (config.verbose) {
-      console.log(`[STALL] Assessment says stalled: ${verdict.reason}`);
+      hlog(`[STALL] Assessment says stalled: ${verdict.reason}`);
     }
   } catch (err) {
     if (config.verbose) {
-      console.log(`[STALL] Assessment error: ${err}`);
+      hlog(`[STALL] Assessment error: ${err}`);
     }
   }
   return null;
@@ -277,6 +278,8 @@ interface StreamHandlerContext {
   currentStepOutputTokens: number;
   /** Timestamp of the last token usage change (tokens still flowing = process alive) */
   lastTokenActivityTime: number;
+  /** Claude Code result event stop_reason (e.g., 'end_turn', 'max_tokens') */
+  stopReason?: string;
 }
 
 function handleSessionCapture(
@@ -590,9 +593,12 @@ function processStreamEvent(parsed: StreamJson, ctx: StreamHandlerContext): void
     return;
   }
 
-  // Handle result events — extract definitive token usage and surface errors
+  // Handle result events — extract definitive token usage, stop_reason, and surface errors
   if (parsed.type === 'result') {
     handleResultTokenUsage(parsed, ctx);
+    if (parsed.stop_reason) {
+      ctx.stopReason = parsed.stop_reason;
+    }
     if (parsed.is_error) {
       const errorMessage = parsed.error || parsed.result || 'Unknown error in result';
       ctx.config.outputCallback?.(`\n[[MSTRO_ERROR:CLAUDE_RESULT_ERROR]] ${errorMessage}\n`);
@@ -733,7 +739,7 @@ function writeImageAttachmentsToStdin(
 ): void {
   claudeProcess.stdin!.on('error', (err) => {
     if (config.verbose) {
-      console.error('[STDIN] Write error:', err.message);
+      herror('[STDIN] Write error:', err.message);
     }
     config.outputCallback?.(`\n[[MSTRO_ERROR:STDIN_WRITE_FAILED]] Failed to send image data to Claude: ${err.message}\n`);
   });
@@ -1002,7 +1008,7 @@ function setupToolTracking(
 /** Log messages when verbose mode is enabled. Extracted to reduce cognitive complexity. */
 function verboseLog(verbose: boolean | undefined, ...msgs: string[]): void {
   if (verbose) {
-    for (const msg of msgs) console.log(msg);
+    for (const msg of msgs) hlog(msg);
   }
 }
 
@@ -1030,12 +1036,17 @@ function spawnAndRegister(
     `[PERF] Command: ${config.claudeCommand} ${args.join(' ')}`,
   );
 
+  const baseEnv = config.sandboxed
+    ? sanitizeEnvForSandbox(process.env, config.workingDir)
+    : { ...process.env };
+  const spawnEnv = config.extraEnv
+    ? { ...baseEnv, ...config.extraEnv }
+    : baseEnv;
+
   const claudeProcess = spawn(config.claudeCommand, args, {
     cwd: config.workingDir,
     detached: true,
-    env: config.sandboxed
-      ? sanitizeEnvForSandbox(process.env, config.workingDir)
-      : { ...process.env },
+    env: spawnEnv,
     stdio: [hasImageAttachments ? 'pipe' : 'ignore', 'pipe', 'pipe']
   });
 
@@ -1210,5 +1221,6 @@ function buildCloseResult(
     postTimeoutOutput: postTimeout,
     resumeBufferedOutput: resumeBuffered,
     apiTokenUsage: hasTokenUsage ? { ...ctx.apiTokenUsage } : undefined,
+    stopReason: ctx.stopReason,
   };
 }

package/server/cli/headless/headless-logger.ts

@@ -0,0 +1,78 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Headless Logger
+ *
+ * Provides AsyncLocalStorage-based logging redirection for headless execution.
+ * When background operations (code review, PM compose/execute) run, their
+ * console output is redirected to log files under ~/.mstro/logs/ instead of
+ * polluting the terminal where the mstro CLI was started.
+ */
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import type { WriteStream } from 'node:fs';
+import { createWriteStream, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+interface LogTarget {
+  log: (...args: unknown[]) => void;
+  error: (...args: unknown[]) => void;
+}
+
+const logContext = new AsyncLocalStorage<LogTarget>();
+
+function formatArgs(args: unknown[]): string {
+  return args.map(a => (typeof a === 'string' ? a : String(a))).join(' ');
+}
+
+/** Log a message. Writes to file when inside runWithFileLogger, otherwise to console. */
+export function hlog(...args: unknown[]): void {
+  const target = logContext.getStore();
+  if (target) {
+    target.log(...args);
+  } else {
+    console.log(...args);
+  }
+}
+
+/** Log an error. Writes to file when inside runWithFileLogger, otherwise to console. */
+export function herror(...args: unknown[]): void {
+  const target = logContext.getStore();
+  if (target) {
+    target.error(...args);
+  } else {
+    console.error(...args);
+  }
+}
+
+const LOG_DIR = join(homedir(), '.mstro', 'logs', 'headless');
+
+/**
+ * Run an async function with all hlog/herror output redirected to a log file.
+ * The log file is created at ~/.mstro/logs/headless/{label}-{timestamp}.log.
+ */
+export async function runWithFileLogger<T>(label: string, fn: () => Promise<T>): Promise<T> {
+  mkdirSync(LOG_DIR, { recursive: true });
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const logPath = join(LOG_DIR, `${label}-${timestamp}.log`);
+  const stream: WriteStream = createWriteStream(logPath, { flags: 'a' });
+
+  const target: LogTarget = {
+    log: (...args: unknown[]) => {
+      stream.write(`[${new Date().toISOString()}] ${formatArgs(args)}\n`);
+    },
+    error: (...args: unknown[]) => {
+      stream.write(`[${new Date().toISOString()}] ERROR: ${formatArgs(args)}\n`);
+    },
+  };
+
+  return logContext.run(target, async () => {
+    try {
+      return await fn();
+    } finally {
+      stream.end();
+    }
+  });
+}

package/server/cli/headless/mcp-config.ts

@@ -8,6 +8,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 import { MCP_SERVER_PATH, MSTRO_ROOT } from '../../utils/paths.js';
+import { herror, hlog } from './headless-logger.js';
 
 /**
  * Load user's MCP servers from ~/.claude.json (global + project-level)
@@ -37,10 +38,10 @@ function loadUserMcpServers(workingDir: string, verbose: boolean): Record<string
     }
 
     if (verbose) {
-      console.log(`[${new Date().toISOString()}] Loaded ${Object.keys(servers).length} user MCP servers from ~/.claude.json`);
+      hlog(`[${new Date().toISOString()}] Loaded ${Object.keys(servers).length} user MCP servers from ~/.claude.json`);
     }
   } catch (parseError: unknown) {
-    console.error(`[${new Date().toISOString()}] Failed to parse ~/.claude.json: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
+    herror(`[${new Date().toISOString()}] Failed to parse ~/.claude.json: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
   }
 
   return servers;
@@ -53,7 +54,7 @@ function loadUserMcpServers(workingDir: string, verbose: boolean): Record<string
 export function generateMcpConfig(workingDir: string, verbose: boolean = false): string | null {
   try {
     if (!existsSync(MCP_SERVER_PATH)) {
-      console.error(`[${new Date().toISOString()}] MCP server not found at ${MCP_SERVER_PATH}`);
+      herror(`[${new Date().toISOString()}] MCP server not found at ${MCP_SERVER_PATH}`);
       return null;
     }
 
@@ -76,12 +77,12 @@ export function generateMcpConfig(workingDir: string, verbose: boolean = false):
     writeFileSync(configPath, JSON.stringify({ mcpServers }, null, 2));
 
     if (verbose) {
-      console.log(`[${new Date().toISOString()}] Generated MCP config at ${configPath} (${Object.keys(mcpServers).length} servers)`);
+      hlog(`[${new Date().toISOString()}] Generated MCP config at ${configPath} (${Object.keys(mcpServers).length} servers)`);
     }
 
     return configPath;
   } catch (error: unknown) {
-    console.error(`[${new Date().toISOString()}] Failed to generate MCP config: ${error instanceof Error ? error.message : String(error)}`);
+    herror(`[${new Date().toISOString()}] Failed to generate MCP config: ${error instanceof Error ? error.message : String(error)}`);
     return null;
   }
 }

package/server/cli/headless/runner.ts

@@ -69,6 +69,7 @@ export class HeadlessRunner {
       maxAutoRetries: config.maxAutoRetries ?? 2,
       onToolTimeout: config.onToolTimeout,
       sandboxed: config.sandboxed,
+      extraEnv: config.extraEnv,
     };
   }
 
@@ -122,6 +123,7 @@ export class HeadlessRunner {
           nativeTimeoutCount: result.nativeTimeoutCount,
           postTimeoutOutput: result.postTimeoutOutput,
           resumeBufferedOutput: result.resumeBufferedOutput,
+          stopReason: result.stopReason,
         };
       }
 
@@ -150,6 +152,7 @@ export class HeadlessRunner {
         nativeTimeoutCount: result.nativeTimeoutCount,
         postTimeoutOutput: result.postTimeoutOutput,
         resumeBufferedOutput: result.resumeBufferedOutput,
+        stopReason: result.stopReason,
       };
     }
 
@@ -168,6 +171,7 @@ export class HeadlessRunner {
       nativeTimeoutCount: result.nativeTimeoutCount,
       postTimeoutOutput: result.postTimeoutOutput,
       resumeBufferedOutput: result.resumeBufferedOutput,
+      stopReason: result.stopReason,
     };
   }
 

package/server/cli/headless/stall-assessor.ts

@@ -17,6 +17,7 @@
  */
 
 import { type ChildProcess, spawn } from 'node:child_process';
+import { hlog } from './headless-logger.js';
 
 export interface StallContext {
   /** The original user prompt being executed */
@@ -137,7 +138,7 @@ export async function assessStall(
   const quick = quickHeuristic(ctx, toolWatchdogActive);
   if (quick) {
     if (verbose) {
-      console.log(`[STALL-ASSESS] Heuristic verdict: ${quick.reason}`);
+      hlog(`[STALL-ASSESS] Heuristic verdict: ${quick.reason}`);
     }
     return quick;
   }
@@ -145,12 +146,12 @@ export async function assessStall(
   // Layer 2: Haiku assessment
   try {
     if (verbose) {
-      console.log('[STALL-ASSESS] Running Haiku assessment...');
+      hlog('[STALL-ASSESS] Running Haiku assessment...');
     }
     return await runHaikuAssessment(ctx, claudeCommand, verbose);
   } catch (err) {
     if (verbose) {
-      console.log(`[STALL-ASSESS] Haiku assessment failed: ${err}`);
+      hlog(`[STALL-ASSESS] Haiku assessment failed: ${err}`);
     }
     // If Haiku fails (timeout, auth issue, etc.), extend cautiously
     return {
@@ -220,13 +221,13 @@ export async function assessToolTimeout(
 
   try {
     if (verbose) {
-      console.log(`[TOOL-ASSESS] Running Haiku assessment for ${toolName} (${elapsedSec}s elapsed)...`);
+      hlog(`[TOOL-ASSESS] Running Haiku assessment for ${toolName} (${elapsedSec}s elapsed)...`);
     }
 
     return await spawnHaikuVerdict(prompt, claudeCommand, verbose, 'TOOL-ASSESS');
   } catch (err) {
     if (verbose) {
-      console.log(`[TOOL-ASSESS] Haiku assessment failed: ${err}`);
+      hlog(`[TOOL-ASSESS] Haiku assessment failed: ${err}`);
     }
     // On failure, default to kill (the tool has already exceeded its timeout)
     return {
@@ -295,7 +296,7 @@ export async function assessContextLoss(
 
   try {
     if (verbose) {
-      console.log(`[CONTEXT-ASSESS] Running Haiku assessment (${ctx.effectiveTimeouts} timeouts, ${ctx.successfulToolCalls} successes, ${ctx.thinkingOutputLength} thinking chars)...`);
+      hlog(`[CONTEXT-ASSESS] Running Haiku assessment (${ctx.effectiveTimeouts} timeouts, ${ctx.successfulToolCalls} successes, ${ctx.thinkingOutputLength} thinking chars)...`);
     }
 
     const raw = await spawnHaikuRaw(prompt, claudeCommand, verbose, 'CONTEXT-ASSESS');
@@ -303,13 +304,13 @@ export async function assessContextLoss(
     const contextLost = parsed.verdict === 'STALLED';
 
     if (verbose) {
-      console.log(`[CONTEXT-ASSESS] Verdict: ${contextLost ? 'LOST' : 'CONTINUED'} — ${parsed.reason}`);
+      hlog(`[CONTEXT-ASSESS] Verdict: ${contextLost ? 'LOST' : 'CONTINUED'} — ${parsed.reason}`);
     }
 
     return { contextLost, reason: parsed.reason };
   } catch (err) {
     if (verbose) {
-      console.log(`[CONTEXT-ASSESS] Haiku assessment failed: ${err}`);
+      hlog(`[CONTEXT-ASSESS] Haiku assessment failed: ${err}`);
     }
     // On failure, assume context was lost (safer to retry than to show a confused response)
     return {
@@ -419,7 +420,7 @@ function spawnHaikuRaw(
 
     proc.stderr!.on('data', (data) => {
       if (verbose) {
-        console.log(`[${label}] haiku stderr: ${data.toString().trim()}`);
+        hlog(`[${label}] haiku stderr: ${data.toString().trim()}`);
       }
     });
 
@@ -434,7 +435,7 @@ function spawnHaikuRaw(
       }
 
       if (verbose) {
-        console.log(`[${label}] Haiku response: ${stdout.trim()}`);
+        hlog(`[${label}] Haiku response: ${stdout.trim()}`);
       }
 
       resolve(stdout.trim());
@@ -521,7 +522,7 @@ export async function assessApproval(
 
   try {
     if (verbose) {
-      console.log('[APPROVAL-ASSESS] Running Haiku assessment...');
+      hlog('[APPROVAL-ASSESS] Running Haiku assessment...');
     }
 
     const raw = await spawnHaikuRaw(prompt, claudeCommand, verbose, 'APPROVAL-ASSESS');
@@ -529,19 +530,96 @@ export async function assessApproval(
     const isApproval = parsed.verdict.includes('APPROVAL');
 
     if (verbose) {
-      console.log(`[APPROVAL-ASSESS] Verdict: ${isApproval ? 'APPROVAL' : 'NEW_TASK'} — ${parsed.reason}`);
+      hlog(`[APPROVAL-ASSESS] Verdict: ${isApproval ? 'APPROVAL' : 'NEW_TASK'} — ${parsed.reason}`);
     }
 
     return { isApproval, reason: parsed.reason };
   } catch (err) {
     if (verbose) {
-      console.log(`[APPROVAL-ASSESS] Haiku assessment failed: ${err}`);
+      hlog(`[APPROVAL-ASSESS] Haiku assessment failed: ${err}`);
     }
     // On failure, assume not an approval (safer to treat as new task)
     return { isApproval: false, reason: `Assessment failed: ${err}` };
   }
 }
 
+// ========== Premature Completion Assessment ==========
+
+export interface PrematureCompletionContext {
+  /** The trailing portion of the assistant response (last ~800 chars) */
+  responseTail: string;
+  /** Total number of successful tool calls in this execution */
+  successfulToolCalls: number;
+  /** Whether extended thinking output was produced */
+  hasThinking: boolean;
+  /** Total response length */
+  responseLength: number;
+}
+
+export interface PrematureCompletionVerdict {
+  /** True if the task appears incomplete and should be auto-continued */
+  isIncomplete: boolean;
+  reason: string;
+}
+
+/**
+ * Assess whether a completed Claude execution ended prematurely.
+ * Called when stop_reason is 'end_turn' but the task may not be finished.
+ * Haiku determines if the trailing response text indicates planned-but-unexecuted work.
+ */
+export async function assessPrematureCompletion(
+  ctx: PrematureCompletionContext,
+  claudeCommand: string,
+  verbose: boolean,
+): Promise<PrematureCompletionVerdict> {
+  const prompt = [
+    'You are analyzing the FINAL output of a Claude Code agent that just exited normally.',
+    'Determine whether the agent finished its task or stopped prematurely mid-work.',
+    '',
+    'Session signals:',
+    `- ${ctx.successfulToolCalls} tool calls completed successfully`,
+    `- Response length: ${ctx.responseLength} characters`,
+    `- Extended thinking: ${ctx.hasThinking ? 'YES' : 'NO'}`,
+    '',
+    `Final response text (last ${ctx.responseTail.length} chars):`,
+    ctx.responseTail,
+    '',
+    'INCOMPLETE signals: "Now I\'ll...", "Let me fix...", "Next I\'ll...", "Moving on to...",',
+    '"I\'ll continue with...", announcing next steps that were never executed,',
+    'describing work that will happen next but no tool call followed.',
+    '',
+    'COMPLETE signals: summarizing what was done, confirming changes, reporting results,',
+    'asking the user a question, past-tense descriptions of completed work,',
+    '"all done", "changes applied", referencing finished state.',
+    '',
+    'Respond in EXACTLY this format (2 lines, no extra text):',
+    'VERDICT: COMPLETE or INCOMPLETE',
+    'REASON: <brief one-line explanation>',
+  ].join('\n');
+
+  try {
+    if (verbose) {
+      hlog(`[PREMATURE-ASSESS] Running Haiku assessment (${ctx.successfulToolCalls} tools, ${ctx.responseLength} chars)...`);
+    }
+
+    const raw = await spawnHaikuRaw(prompt, claudeCommand, verbose, 'PREMATURE-ASSESS');
+    const parsed = parseVerdictResponse(raw);
+    const isIncomplete = parsed.verdict.includes('INCOMPLETE');
+
+    if (verbose) {
+      hlog(`[PREMATURE-ASSESS] Verdict: ${isIncomplete ? 'INCOMPLETE' : 'COMPLETE'} — ${parsed.reason}`);
+    }
+
+    return { isIncomplete, reason: parsed.reason };
+  } catch (err) {
+    if (verbose) {
+      hlog(`[PREMATURE-ASSESS] Haiku assessment failed: ${err}`);
+    }
+    // On failure, don't retry — safer to let the user decide than to auto-continue incorrectly
+    return { isIncomplete: false, reason: `Assessment failed: ${err}` };
+  }
+}
+
 // ========== Best Result Comparison ==========
 
 export interface BestResultContext {
@@ -602,7 +680,7 @@ export async function assessBestResult(
 
   try {
     if (verbose) {
-      console.log('[BEST-RESULT] Running Haiku assessment...');
+      hlog('[BEST-RESULT] Running Haiku assessment...');
     }
 
     const raw = await spawnHaikuRaw(prompt, claudeCommand, verbose, 'BEST-RESULT');
@@ -610,13 +688,13 @@ export async function assessBestResult(
     const winner: 'A' | 'B' = parsed.verdict.includes('B') ? 'B' : 'A';
 
     if (verbose) {
-      console.log(`[BEST-RESULT] Verdict: ${winner} — ${parsed.reason}`);
+      hlog(`[BEST-RESULT] Verdict: ${winner} — ${parsed.reason}`);
     }
 
     return { winner, reason: parsed.reason };
   } catch (err) {
     if (verbose) {
-      console.log(`[BEST-RESULT] Haiku assessment failed: ${err}`);
+      hlog(`[BEST-RESULT] Haiku assessment failed: ${err}`);
     }
     // On failure, prefer A (the previously-tracked best result)
     return { winner: 'A', reason: `Assessment failed: ${err}` };
@@ -671,7 +749,7 @@ export async function classifyError(
 
   try {
     if (verbose) {
-      console.log('[ERROR-CLASSIFY] Running Haiku assessment...');
+      hlog('[ERROR-CLASSIFY] Running Haiku assessment...');
     }
 
     const raw = await spawnHaikuRaw(prompt, claudeCommand, verbose, 'ERROR-CLASSIFY');
@@ -691,13 +769,13 @@ export async function classifyError(
     if (category === 'UNKNOWN' || !message) return null;
 
     if (verbose) {
-      console.log(`[ERROR-CLASSIFY] Verdict: ${category} — ${message}`);
+      hlog(`[ERROR-CLASSIFY] Verdict: ${category} — ${message}`);
     }
 
     return { errorCode: category, message };
   } catch (err) {
     if (verbose) {
-      console.log(`[ERROR-CLASSIFY] Haiku assessment failed: ${err}`);
+      hlog(`[ERROR-CLASSIFY] Haiku assessment failed: ${err}`);
     }
     return null;
   }

package/server/cli/headless/tool-watchdog.ts

@@ -14,6 +14,7 @@
  * 3. Haiku tiebreaker: optional AI assessment before killing ambiguous cases
  */
 
+import { hlog } from './headless-logger.js';
 import type {
   ExecutionCheckpoint,
   ToolDurationTracker,
@@ -167,7 +168,7 @@ export class ToolWatchdog {
         sampleCount: 1,
       });
       if (this.verbose) {
-        console.log(`[WATCHDOG] ${toolName}: first sample ${durationMs}ms, initial timeout ${this.getTimeout(toolName)}ms`);
+        hlog(`[WATCHDOG] ${toolName}: first sample ${durationMs}ms, initial timeout ${this.getTimeout(toolName)}ms`);
       }
       return;
     }
@@ -178,7 +179,7 @@ export class ToolWatchdog {
     tracker.sampleCount++;
 
     if (this.verbose) {
-      console.log(`[WATCHDOG] ${toolName}: sample #${tracker.sampleCount} ${durationMs}ms, est=${Math.round(tracker.estimatedDuration)}ms, dev=${Math.round(tracker.deviation)}ms, timeout=${this.getTimeout(toolName)}ms`);
+      hlog(`[WATCHDOG] ${toolName}: sample #${tracker.sampleCount} ${durationMs}ms, est=${Math.round(tracker.estimatedDuration)}ms, dev=${Math.round(tracker.deviation)}ms, timeout=${this.getTimeout(toolName)}ms`);
     }
   }
 
@@ -208,7 +209,7 @@ export class ToolWatchdog {
     const profile = this.getProfile(toolName);
 
     if (this.verbose) {
-      console.log(`[WATCHDOG] Starting watch: ${toolName} (${toolId}), timeout=${Math.round(timeoutMs / 1000)}s`);
+      hlog(`[WATCHDOG] Starting watch: ${toolName} (${toolId}), timeout=${Math.round(timeoutMs / 1000)}s`);
     }
 
     const timer = setTimeout(async () => {
@@ -245,7 +246,7 @@ export class ToolWatchdog {
 
     if (!profile.useHaikuTiebreaker || !this.onTiebreaker || watch.tiebreakerAttempted) {
       if (this.verbose) {
-        console.log(`[WATCHDOG] ${toolName} (${toolId}) timed out after ${Math.round(elapsedMs / 1000)}s, killing`);
+        hlog(`[WATCHDOG] ${toolName} (${toolId}) timed out after ${Math.round(elapsedMs / 1000)}s, killing`);
       }
       return false;
     }
@@ -265,7 +266,7 @@ export class ToolWatchdog {
     watch.tiebreakerAttempted = true;
 
     if (this.verbose) {
-      console.log(`[WATCHDOG] ${toolName} (${toolId}) hit timeout after ${Math.round(elapsedMs / 1000)}s, running tiebreaker...`);
+      hlog(`[WATCHDOG] ${toolName} (${toolId}) hit timeout after ${Math.round(elapsedMs / 1000)}s, running tiebreaker...`);
     }
 
     try {
@@ -274,7 +275,7 @@ export class ToolWatchdog {
 
       if (verdict.action === 'extend') {
         if (this.verbose) {
-          console.log(`[WATCHDOG] Tiebreaker: extend ${toolName} by ${Math.round(verdict.extensionMs / 1000)}s — ${verdict.reason}`);
+          hlog(`[WATCHDOG] Tiebreaker: extend ${toolName} by ${Math.round(verdict.extensionMs / 1000)}s — ${verdict.reason}`);
         }
         this.scheduleExtensionTimeout(watch, toolId, toolName, verdict.extensionMs, onTimeout);
         watch.timeoutMs = elapsedMs + verdict.extensionMs;
@@ -282,11 +283,11 @@ export class ToolWatchdog {
       }
 
       if (this.verbose) {
-        console.log(`[WATCHDOG] Tiebreaker: kill ${toolName} — ${verdict.reason}`);
+        hlog(`[WATCHDOG] Tiebreaker: kill ${toolName} — ${verdict.reason}`);
       }
     } catch (err) {
       if (this.verbose) {
-        console.log(`[WATCHDOG] Tiebreaker failed: ${err}, proceeding with kill`);
+        hlog(`[WATCHDOG] Tiebreaker failed: ${err}, proceeding with kill`);
       }
     }
 
@@ -305,7 +306,7 @@ export class ToolWatchdog {
       const w = this.activeWatches.get(toolId);
       if (!w) return;
       if (this.verbose) {
-        console.log(`[WATCHDOG] ${toolName} (${toolId}) still running after extension, killing`);
+        hlog(`[WATCHDOG] ${toolName} (${toolId}) still running after extension, killing`);
       }
       // Don't delete the watch — buildCheckpoint() needs it.
       // handleToolTimeout() calls clearAll() after building the checkpoint.

package/server/cli/headless/types.ts

@@ -121,6 +121,8 @@ export interface HeadlessConfig {
   onToolTimeout?: (checkpoint: ExecutionCheckpoint) => void;
   /** When true, spawn Claude with sanitized env (strips secrets, HOME=workingDir) */
   sandboxed?: boolean;
+  /** Extra environment variables to merge into the spawned Claude process env */
+  extraEnv?: Record<string, string>;
 }
 
 export interface SessionState {
@@ -165,6 +167,8 @@ export interface SessionResult {
   /** Assistant text buffered during resume assessment — held back until thinking/tool activity
    *  confirms Claude has context. Undefined when not in resume mode or buffer was flushed. */
   resumeBufferedOutput?: string;
+  /** Claude Code result event stop_reason: 'end_turn', 'max_tokens', or undefined if not captured */
+  stopReason?: string;
 }
 
 export interface ToolUseAccumulator {
@@ -200,10 +204,12 @@ export interface ExecutionResult {
   resumeBufferedOutput?: string;
   /** Actual API token usage from Claude Code stream events (summed across all turns) */
   apiTokenUsage?: { inputTokens: number; outputTokens: number };
+  /** Claude Code result event stop_reason: 'end_turn', 'max_tokens', or undefined if not captured */
+  stopReason?: string;
 }
 
 /** Resolved config with all defaults applied */
-export type ResolvedHeadlessConfig = Omit<Required<HeadlessConfig>, 'outputCallback' | 'thinkingCallback' | 'toolUseCallback' | 'tokenUsageCallback' | 'continueSession' | 'claudeSessionId' | 'imageAttachments' | 'model' | 'toolTimeoutProfiles' | 'onToolTimeout' | 'sandboxed'> & {
+export type ResolvedHeadlessConfig = Omit<Required<HeadlessConfig>, 'outputCallback' | 'thinkingCallback' | 'toolUseCallback' | 'tokenUsageCallback' | 'continueSession' | 'claudeSessionId' | 'imageAttachments' | 'model' | 'toolTimeoutProfiles' | 'onToolTimeout' | 'sandboxed' | 'extraEnv'> & {
   outputCallback?: (text: string) => void;
   thinkingCallback?: (text: string) => void;
   toolUseCallback?: (event: ToolUseEvent) => void;
@@ -215,4 +221,7 @@ export type ResolvedHeadlessConfig = Omit<Required<HeadlessConfig>, 'outputCallb
   toolTimeoutProfiles?: Record<string, Partial<ToolTimeoutProfile>>;
   onToolTimeout?: (checkpoint: ExecutionCheckpoint) => void;
   sandboxed?: boolean;
+  extraEnv?: Record<string, string>;
 };
+
+