mstro-app 0.2.0 → 0.3.1

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

@@ -21,11 +21,26 @@ import type {
   ToolUseEvent,
 } from './types.js';
 
+/** Parsed JSON from Claude CLI stream — structure varies by event type */
+// biome-ignore lint/suspicious/noExplicitAny: external CLI stream JSON with heterogeneous shapes
+type StreamJson = any;
+
 export interface ClaudeInvokerOptions {
   config: ResolvedHeadlessConfig;
   runningProcesses: Map<number, ChildProcess>;
 }
 
+// ========== Signal Helpers ==========
+
+/** Map a Node.js signal name to its numeric value for exit code computation */
+function signalToNumber(signal: string): number | undefined {
+  const map: Record<string, number> = {
+    SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6,
+    SIGKILL: 9, SIGTERM: 15, SIGUSR1: 10, SIGUSR2: 12,
+  };
+  return map[signal];
+}
+
 // ========== Stall Detection Helpers ==========
 
 /** Summarize a tool's input for stall assessment context */
@@ -261,10 +276,16 @@ interface StreamHandlerContext {
   resumeAssessmentActive: boolean;
   /** Buffered assistant text during resume assessment */
   resumeAssessmentBuffer: string;
+  /** Cumulative API token usage from message_start/message_delta events */
+  apiTokenUsage: { inputTokens: number; outputTokens: number };
+  /** Tracks cumulative output_tokens within the current step (message_delta is cumulative per-step) */
+  currentStepOutputTokens: number;
+  /** Timestamp of the last token usage change (tokens still flowing = process alive) */
+  lastTokenActivityTime: number;
 }
 
 function handleSessionCapture(
-  parsed: any,
+  parsed: StreamJson,
   captured: { claudeSessionId?: string }
 ): void {
   if (parsed.type === 'system' && parsed.subtype === 'init' && parsed.session_id) {
@@ -275,7 +296,7 @@ function handleSessionCapture(
   }
 }
 
-function handleThinkingDelta(event: any, ctx: StreamHandlerContext): string {
+function handleThinkingDelta(event: StreamJson, ctx: StreamHandlerContext): string {
   if (
     event.type !== 'content_block_delta' ||
     event.delta?.type !== 'thinking_delta' ||
@@ -307,7 +328,7 @@ function handleThinkingDelta(event: any, ctx: StreamHandlerContext): string {
   return updated;
 }
 
-function handleTextDelta(event: any, ctx: StreamHandlerContext): string {
+function handleTextDelta(event: StreamJson, ctx: StreamHandlerContext): string {
   if (
     event.type !== 'content_block_delta' ||
     event.delta?.type !== 'text_delta' ||
@@ -349,7 +370,7 @@ function handleTextDelta(event: any, ctx: StreamHandlerContext): string {
   return updated;
 }
 
-function handleToolStart(event: any, ctx: StreamHandlerContext): void {
+function handleToolStart(event: StreamJson, ctx: StreamHandlerContext): void {
   if (
     event.type !== 'content_block_start' ||
     event.content_block?.type !== 'tool_use'
@@ -382,7 +403,7 @@ function handleToolStart(event: any, ctx: StreamHandlerContext): void {
   }
 }
 
-function handleToolInputDelta(event: any, ctx: StreamHandlerContext): void {
+function handleToolInputDelta(event: StreamJson, ctx: StreamHandlerContext): void {
   if (
     event.type !== 'content_block_delta' ||
     event.delta?.type !== 'input_json_delta'
@@ -403,7 +424,7 @@ function handleToolInputDelta(event: any, ctx: StreamHandlerContext): void {
   }
 }
 
-function handleToolComplete(event: any, ctx: StreamHandlerContext): void {
+function handleToolComplete(event: StreamJson, ctx: StreamHandlerContext): void {
   if (event.type !== 'content_block_stop') {
     return;
   }
@@ -414,7 +435,7 @@ function handleToolComplete(event: any, ctx: StreamHandlerContext): void {
     return;
   }
 
-  let completeInput: any = {};
+  let completeInput: Record<string, unknown> = {};
   try {
     completeInput = JSON.parse(toolBuffer.inputJson);
   } catch (_e) {
@@ -428,6 +449,9 @@ function handleToolComplete(event: any, ctx: StreamHandlerContext): void {
     startTime: toolBuffer.startTime
   });
 
+  // Clean up the input buffer — it's no longer needed after accumulation
+  ctx.toolInputBuffers.delete(index);
+
   if (ctx.config.toolUseCallback) {
     ctx.config.toolUseCallback({
       type: 'tool_complete',
@@ -439,7 +463,81 @@ function handleToolComplete(event: any, ctx: StreamHandlerContext): void {
   }
 }
 
-function handleToolResult(parsed: any, ctx: StreamHandlerContext): void {
+/** Accumulate input tokens from a message_start event. Returns true if any tokens were added. */
+function handleMessageStartTokens(event: StreamJson, ctx: StreamHandlerContext): boolean {
+  if (event.type !== 'message_start' || !event.message?.usage) return false;
+  const usage = event.message.usage;
+  ctx.currentStepOutputTokens = 0;
+  let changed = false;
+  if (typeof usage.input_tokens === 'number') {
+    ctx.apiTokenUsage.inputTokens += usage.input_tokens;
+    changed = true;
+  }
+  if (typeof usage.cache_creation_input_tokens === 'number') {
+    ctx.apiTokenUsage.inputTokens += usage.cache_creation_input_tokens;
+    changed = true;
+  }
+  if (typeof usage.cache_read_input_tokens === 'number') {
+    ctx.apiTokenUsage.inputTokens += usage.cache_read_input_tokens;
+    changed = true;
+  }
+  verboseLog(ctx.config.verbose,
+    `[TOKENS] message_start: input=${usage.input_tokens ?? 0} cache_create=${usage.cache_creation_input_tokens ?? 0} cache_read=${usage.cache_read_input_tokens ?? 0} → total_input=${ctx.apiTokenUsage.inputTokens}`);
+  return changed;
+}
+
+/** Accumulate output tokens from a message_delta event. Returns true if any tokens were added.
+ * message_delta carries CUMULATIVE output token count for the current step.
+ * Per Anthropic docs: "The token counts shown in the usage field of the
+ * message_delta event are cumulative" and there can be "one or more message_delta
+ * events" per message. We track the delta from the previous value to avoid
+ * double-counting when multiple message_delta events fire per step. */
+function handleMessageDeltaTokens(event: StreamJson, ctx: StreamHandlerContext): boolean {
+  if (event.type !== 'message_delta' || !event.usage) return false;
+  if (typeof event.usage.output_tokens !== 'number') return false;
+  const increment = event.usage.output_tokens - ctx.currentStepOutputTokens;
+  verboseLog(ctx.config.verbose,
+    `[TOKENS] message_delta: output=${event.usage.output_tokens} (step_prev=${ctx.currentStepOutputTokens} increment=${increment}) → total_output=${ctx.apiTokenUsage.outputTokens + Math.max(increment, 0)}`);
+  if (increment <= 0) return false;
+  ctx.apiTokenUsage.outputTokens += increment;
+  ctx.currentStepOutputTokens = event.usage.output_tokens;
+  return true;
+}
+
+function handleTokenUsage(event: StreamJson, ctx: StreamHandlerContext): void {
+  const changed = handleMessageStartTokens(event, ctx) || handleMessageDeltaTokens(event, ctx);
+  if (changed) {
+    ctx.lastTokenActivityTime = Date.now();
+    ctx.config.tokenUsageCallback?.({ ...ctx.apiTokenUsage });
+  }
+}
+
+/**
+ * Extract definitive token usage from the result event emitted at the end of a Claude session.
+ * The result event's `usage` field contains the authoritative total — it overrides any
+ * accumulated stream-based counts which may be incomplete (e.g., when extended thinking
+ * suppresses stream_event emissions).
+ */
+function handleResultTokenUsage(parsed: StreamJson, ctx: StreamHandlerContext): void {
+  if (!parsed.usage) return;
+  const u = parsed.usage;
+  const input = (typeof u.input_tokens === 'number' ? u.input_tokens : 0)
+    + (typeof u.cache_creation_input_tokens === 'number' ? u.cache_creation_input_tokens : 0)
+    + (typeof u.cache_read_input_tokens === 'number' ? u.cache_read_input_tokens : 0);
+  const output = typeof u.output_tokens === 'number' ? u.output_tokens : 0;
+
+  if (input > 0 || output > 0) {
+    verboseLog(ctx.config.verbose,
+      `[TOKENS] Result event usage: input=${input} output=${output} ` +
+      `(stream accumulated: input=${ctx.apiTokenUsage.inputTokens} output=${ctx.apiTokenUsage.outputTokens})`);
+    // Replace with authoritative counts from the result event
+    ctx.apiTokenUsage = { inputTokens: input, outputTokens: output };
+    ctx.lastTokenActivityTime = Date.now();
+    ctx.config.tokenUsageCallback?.({ ...ctx.apiTokenUsage });
+  }
+}
+
+function handleToolResult(parsed: StreamJson, ctx: StreamHandlerContext): void {
   if (parsed.type !== 'user' || !parsed.message?.content) {
     return;
   }
@@ -489,7 +587,7 @@ function processStreamLines(
   return remainder;
 }
 
-function processStreamEvent(parsed: any, ctx: StreamHandlerContext): void {
+function processStreamEvent(parsed: StreamJson, ctx: StreamHandlerContext): void {
   // Handle error events from Claude CLI (API errors, model errors, etc.)
   if (parsed.type === 'error') {
     const errorMessage = parsed.error?.message || parsed.message || JSON.stringify(parsed);
@@ -497,11 +595,14 @@ function processStreamEvent(parsed: any, ctx: StreamHandlerContext): void {
     return;
   }
 
-  // Handle result events that contain error info
-  if (parsed.type === 'result' && parsed.is_error) {
-    const errorMessage = parsed.error || parsed.result || 'Unknown error in result';
-    ctx.config.outputCallback?.(`\n[[MSTRO_ERROR:CLAUDE_RESULT_ERROR]] ${errorMessage}\n`);
-    return;
+  // Handle result events — extract definitive token usage and surface errors
+  if (parsed.type === 'result') {
+    handleResultTokenUsage(parsed, ctx);
+    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`);
+      return;
+    }
   }
 
   if (parsed.type === 'stream_event' && parsed.event) {
@@ -511,6 +612,7 @@ function processStreamEvent(parsed: any, ctx: StreamHandlerContext): void {
     handleToolStart(event, ctx);
     handleToolInputDelta(event, ctx);
     handleToolComplete(event, ctx);
+    handleTokenUsage(event, ctx);
   }
   handleToolResult(parsed, ctx);
 }
@@ -672,11 +774,13 @@ async function runStallCheckTick(
     claudeProcess: ChildProcess;
     stallCheckInterval: ReturnType<typeof setInterval>;
     config: ResolvedHeadlessConfig;
+    lastTokenActivityTime: number;
   },
 ): Promise<void> {
   const now = Date.now();
   const silenceMs = now - state.lastActivityTime;
   const totalElapsed = now - opts.perfStart;
+  const tokenSilenceMs = now - opts.lastTokenActivityTime;
 
   if (totalElapsed >= opts.stallHardCapMs) {
     terminateStallProcess(opts.claudeProcess, opts.stallCheckInterval, opts.config,
@@ -685,6 +789,13 @@ async function runStallCheckTick(
     return;
   }
 
+  // Token activity pushes the kill deadline forward — tokens flowing means
+  // the process is alive even if stdout is silent (e.g. silent thinking).
+  if (tokenSilenceMs < 60_000 && now < state.currentKillDeadline) {
+    const killMs = opts.config.stallKillMs ?? 1_800_000;
+    state.currentKillDeadline = Math.max(state.currentKillDeadline, now + killMs);
+  }
+
   if (now >= state.currentKillDeadline) {
     terminateStallProcess(opts.claudeProcess, opts.stallCheckInterval, opts.config,
       `\n[[MSTRO_ERROR:EXECUTION_STALLED]] No output for ${Math.round(silenceMs / 60_000)} minutes. Terminating process.\n`
@@ -703,6 +814,7 @@ async function runStallCheckTick(
     pendingToolNames: new Set(opts.pendingTools.values()),
     totalToolCalls: opts.totalToolCalls,
     elapsedTotalMs: totalElapsed,
+    tokenSilenceMs,
   };
 
   if (opts.stallAssessEnabled && state.extensionsGranted < opts.maxExtensions) {
@@ -762,12 +874,13 @@ function onToolStart(event: ToolUseEvent, s: ToolTrackingState): void {
 /** Handle tool_complete events. Extracted to reduce cognitive complexity. */
 function onToolComplete(event: ToolUseEvent, s: ToolTrackingState): void {
   const id = event.toolId!;
-  s.counters.lastToolInputSummary = summarizeToolInput(event.completeInput);
-  s.toolIdToInput.set(id, event.completeInput);
+  const input = event.completeInput ?? {};
+  s.counters.lastToolInputSummary = summarizeToolInput(input);
+  s.toolIdToInput.set(id, input);
   if (!s.watchdog) return;
   const toolName = s.toolIdToName.get(id);
   if (toolName) {
-    s.watchdog.startWatch(id, toolName, event.completeInput, () => { s.onTimeout(id); });
+    s.watchdog.startWatch(id, toolName, input, () => { s.onTimeout(id); });
   }
 }
 
@@ -847,8 +960,12 @@ function setupToolTracking(
     ? new ToolWatchdog({
         profiles: config.toolTimeoutProfiles,
         verbose: config.verbose,
-        onTiebreaker: async (toolName, toolInput, elapsedMs) => {
-          return assessToolTimeout(toolName, toolInput, elapsedMs, config.claudeCommand, config.verbose);
+        onTiebreaker: async (toolName, toolInput, elapsedMs, tokenSilenceMs) => {
+          return assessToolTimeout(toolName, toolInput, elapsedMs, config.claudeCommand, config.verbose, tokenSilenceMs);
+        },
+        getTokenSilenceMs: () => {
+          const last = ctx.lastTokenActivityTime;
+          return last > 0 ? Date.now() - last : undefined;
         },
       })
     : null;
@@ -978,6 +1095,9 @@ export async function executeClaudeCommand(
     nativeTimeoutDetector: new NativeTimeoutDetector(),
     resumeAssessmentActive: isResumeMode,
     resumeAssessmentBuffer: '',
+    apiTokenUsage: { inputTokens: 0, outputTokens: 0 },
+    currentStepOutputTokens: 0,
+    lastTokenActivityTime: Date.now(),
   };
 
   // Stall detection state (mutable object shared with runStallCheckTick)
@@ -1044,7 +1164,7 @@ export async function executeClaudeCommand(
     runStallCheckTick(stallState, {
       perfStart, stallWarningMs, stallHardCapMs, maxExtensions, stallAssessEnabled,
       toolWatchdogActive, prompt, pendingTools, lastToolInputSummary: toolCounters.lastToolInputSummary, totalToolCalls: toolCounters.totalToolCalls,
-      claudeProcess, stallCheckInterval, config,
+      claudeProcess, stallCheckInterval, config, lastTokenActivityTime: ctx.lastTokenActivityTime,
     });
   }, 10_000);
 
@@ -1052,38 +1172,47 @@ export async function executeClaudeCommand(
   toolTracking.setKillContext(claudeProcess, stallCheckInterval);
 
   return new Promise((resolve, reject) => {
-    claudeProcess.on('close', async (code) => {
+    claudeProcess.on('close', async (code, signal) => {
       clearInterval(stallCheckInterval);
       watchdog?.clearAll();
-
-      const postTimeout = flushNativeTimeoutBuffers(ctx);
       await classifyUnmatchedStderr(stderr, errorAlreadySurfaced, code, config);
-      const resumeBuffered = ctx.resumeAssessmentActive ? (ctx.resumeAssessmentBuffer || undefined) : undefined;
-
-      if (claudeProcess.pid) {
-        runningProcesses.delete(claudeProcess.pid);
-      }
-      resolve({
-        output: stdout,
-        error: stderr || undefined,
-        exitCode: code || 0,
-        assistantResponse: ctx.accumulatedAssistantResponse || undefined,
-        thinkingOutput: ctx.accumulatedThinking || undefined,
-        toolUseHistory: ctx.accumulatedToolUse.length > 0 ? ctx.accumulatedToolUse : undefined,
-        claudeSessionId: sessionCapture.claudeSessionId,
-        nativeTimeoutCount: ctx.nativeTimeoutDetector.timeoutCount || undefined,
-        postTimeoutOutput: postTimeout,
-        resumeBufferedOutput: resumeBuffered,
-      });
+      if (claudeProcess.pid) runningProcesses.delete(claudeProcess.pid);
+      resolve(buildCloseResult(ctx, stdout, stderr, code, signal, sessionCapture));
     });
 
     claudeProcess.on('error', (error: NodeJS.ErrnoException) => {
       clearInterval(stallCheckInterval);
       watchdog?.clearAll();
-      if (claudeProcess.pid) {
-        runningProcesses.delete(claudeProcess.pid);
-      }
+      if (claudeProcess.pid) runningProcesses.delete(claudeProcess.pid);
       handleSpawnError(error, config, reject);
     });
   });
 }
+
+function buildCloseResult(
+  ctx: StreamHandlerContext,
+  stdout: string,
+  stderr: string,
+  code: number | null,
+  signal: NodeJS.Signals | null,
+  sessionCapture: { claudeSessionId?: string },
+): ExecutionResult {
+  const postTimeout = flushNativeTimeoutBuffers(ctx);
+  const resumeBuffered = ctx.resumeAssessmentActive ? (ctx.resumeAssessmentBuffer || undefined) : undefined;
+  const exitCode = code ?? (signal ? 128 + (signalToNumber(signal) ?? 0) : 0);
+  const hasTokenUsage = ctx.apiTokenUsage.inputTokens > 0 || ctx.apiTokenUsage.outputTokens > 0;
+  return {
+    output: stdout,
+    error: stderr || undefined,
+    exitCode,
+    signalName: signal || undefined,
+    assistantResponse: ctx.accumulatedAssistantResponse || undefined,
+    thinkingOutput: ctx.accumulatedThinking || undefined,
+    toolUseHistory: ctx.accumulatedToolUse.length > 0 ? ctx.accumulatedToolUse : undefined,
+    claudeSessionId: sessionCapture.claudeSessionId,
+    nativeTimeoutCount: ctx.nativeTimeoutDetector.timeoutCount || undefined,
+    postTimeoutOutput: postTimeout,
+    resumeBufferedOutput: resumeBuffered,
+    apiTokenUsage: hasTokenUsage ? { ...ctx.apiTokenUsage } : undefined,
+  };
+}

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

@@ -12,8 +12,8 @@ import { MCP_SERVER_PATH, MSTRO_ROOT } from '../../utils/paths.js';
 /**
  * Load user's MCP servers from ~/.claude.json (global + project-level)
  */
-function loadUserMcpServers(workingDir: string, verbose: boolean): Record<string, any> {
-  const servers: Record<string, any> = {};
+function loadUserMcpServers(workingDir: string, verbose: boolean): Record<string, unknown> {
+  const servers: Record<string, unknown> = {};
   const claudeConfigPath = join(homedir(), '.claude.json');
 
   if (!existsSync(claudeConfigPath)) {
@@ -29,7 +29,7 @@ function loadUserMcpServers(workingDir: string, verbose: boolean): Record<string
 
     if (claudeConfig.projects && typeof claudeConfig.projects === 'object') {
       for (const [projectPath, projectConfig] of Object.entries(claudeConfig.projects)) {
-        const projectServers = (projectConfig as any)?.mcpServers;
+        const projectServers = (projectConfig as Record<string, unknown>)?.mcpServers;
         if (workingDir.startsWith(projectPath) && typeof projectServers === 'object') {
           Object.assign(servers, projectServers);
         }
@@ -39,8 +39,8 @@ 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`);
     }
-  } catch (parseError: any) {
-    console.error(`[${new Date().toISOString()}] Failed to parse ~/.claude.json: ${parseError.message}`);
+  } catch (parseError: unknown) {
+    console.error(`[${new Date().toISOString()}] Failed to parse ~/.claude.json: ${parseError instanceof Error ? parseError.message : String(parseError)}`);
   }
 
   return servers;
@@ -57,7 +57,7 @@ export function generateMcpConfig(workingDir: string, verbose: boolean = false):
       return null;
     }
 
-    const mcpServers: Record<string, any> = {
+    const mcpServers: Record<string, unknown> = {
       'mstro-bouncer': {
         command: 'npx',
         args: ['tsx', MCP_SERVER_PATH],
@@ -80,8 +80,8 @@ export function generateMcpConfig(workingDir: string, verbose: boolean = false):
     }
 
     return configPath;
-  } catch (error: any) {
-    console.error(`[${new Date().toISOString()}] Failed to generate MCP config: ${error.message}`);
+  } catch (error: unknown) {
+    console.error(`[${new Date().toISOString()}] Failed to generate MCP config: ${error instanceof Error ? error.message : String(error)}`);
     return null;
   }
 }

package/server/cli/headless/runner.ts

@@ -89,6 +89,29 @@ export class HeadlessRunner {
     const result = await this.executePromptCommand(enrichedPrompt, 'main', 1);
 
     if (result.exitCode !== 0) {
+      // Signal exits (128+) with meaningful output are successful completions —
+      // Claude finished its work but the process was killed by signal (e.g., stall watchdog SIGTERM)
+      const isSignalExit = result.exitCode >= 128;
+      const hasOutput = !!(result.assistantResponse || (result.toolUseHistory && result.toolUseHistory.length > 0));
+
+      if (isSignalExit && hasOutput) {
+        const tokens = estimateTokensFromOutput(result.output);
+        return {
+          completed: true,
+          needsHandoff: false,
+          totalTokens: tokens,
+          sessionId,
+          signalName: result.signalName,
+          assistantResponse: result.assistantResponse,
+          thinkingOutput: result.thinkingOutput,
+          toolUseHistory: result.toolUseHistory,
+          claudeSessionId: result.claudeSessionId,
+          nativeTimeoutCount: result.nativeTimeoutCount,
+          postTimeoutOutput: result.postTimeoutOutput,
+          resumeBufferedOutput: result.resumeBufferedOutput,
+        };
+      }
+
       // Build meaningful error: prefer stderr, fall back to non-JSON stdout lines
       let errorMessage = result.error;
       if (!errorMessage && result.output) {
@@ -106,6 +129,7 @@ export class HeadlessRunner {
         totalTokens: 0,
         sessionId,
         error: errorMessage || `Claude exited with code ${result.exitCode}`,
+        signalName: result.signalName,
         assistantResponse: result.assistantResponse,
         thinkingOutput: result.thinkingOutput,
         toolUseHistory: result.toolUseHistory,
@@ -123,6 +147,7 @@ export class HeadlessRunner {
       needsHandoff: false,
       totalTokens: tokens,
       sessionId,
+      signalName: result.signalName,
       assistantResponse: result.assistantResponse,
       thinkingOutput: result.thinkingOutput,
       toolUseHistory: result.toolUseHistory,
@@ -150,12 +175,40 @@ export class HeadlessRunner {
   }
 
   /**
-   * Cleanup on exit
+   * Cleanup on exit — SIGTERM all tracked processes, then SIGKILL stragglers after 5s
    */
   cleanup(): void {
-    for (const [_pid, process] of this.runningProcesses) {
-      process.kill();
+    if (this.runningProcesses.size === 0) return;
+
+    const pids = new Set<number>();
+    for (const [pid, proc] of this.runningProcesses) {
+      pids.add(pid);
+      try { proc.kill('SIGTERM'); } catch { /* already dead */ }
+    }
+
+    // SIGKILL fallback after 5 seconds for any process that didn't exit
+    setTimeout(() => {
+      for (const [pid, proc] of this.runningProcesses) {
+        if (pids.has(pid) && !proc.killed) {
+          try { proc.kill('SIGKILL'); } catch { /* already dead */ }
+        }
+      }
+      this.runningProcesses.clear();
+    }, 5000);
+  }
+
+  /**
+   * Sweep for zombie processes — entries in runningProcesses whose underlying
+   * process has already exited but whose 'close' event was missed.
+   */
+  sweepZombies(): number {
+    let swept = 0;
+    for (const [pid, proc] of this.runningProcesses) {
+      if (proc.exitCode !== null || proc.killed) {
+        this.runningProcesses.delete(pid);
+        swept++;
+      }
     }
-    this.runningProcesses.clear();
+    return swept;
   }
 }

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

@@ -35,6 +35,8 @@ export interface StallContext {
   totalToolCalls: number;
   /** Total wall-clock time since process started (ms) */
   elapsedTotalMs: number;
+  /** Time since the last token usage event (ms). Undefined if no token events yet. */
+  tokenSilenceMs?: number;
 }
 
 export interface StallVerdict {
@@ -57,6 +59,17 @@ function quickHeuristic(ctx: StallContext, toolWatchdogActive = false): StallVer
   const pendingNames = ctx.pendingToolNames ?? new Set<string>();
   const hasPendingTools = ctx.pendingToolCount > 0;
 
+  // Tokens still flowing = process is alive and actively processing.
+  // Extend generously when token activity is recent (< 60s), regardless
+  // of stdout silence. This covers silent thinking and tool result processing.
+  if (ctx.tokenSilenceMs !== undefined && ctx.tokenSilenceMs < 60_000) {
+    return {
+      action: 'extend',
+      extensionMs: 10 * 60_000,
+      reason: `Tokens still flowing (last activity ${Math.round(ctx.tokenSilenceMs / 1000)}s ago) — process is alive`,
+    };
+  }
+
   // When the watchdog is active and tools are pending, always defer.
   // The watchdog manages per-tool timeouts; the stall detector should only
   // fire when no tools are running and there's genuine silence.
@@ -156,6 +169,7 @@ export async function assessToolTimeout(
   elapsedMs: number,
   claudeCommand: string,
   verbose: boolean,
+  tokenSilenceMs?: number,
 ): Promise<StallVerdict> {
   const elapsedSec = Math.round(elapsedMs / 1000);
 
@@ -181,13 +195,19 @@ export async function assessToolTimeout(
   };
   const toolDesc = toolDescriptions[toolName] || `executes the ${toolName} tool`;
 
+  const tokenLine = tokenSilenceMs !== undefined
+    ? `Token activity: last token event ${Math.round(tokenSilenceMs / 1000)}s ago (recent tokens = process is alive and processing)`
+    : 'Token activity: no token events observed';
+
   const prompt = [
     `You are a process health monitor. A ${toolName} tool call has been running for ${elapsedSec}s.`,
     `${toolName} ${toolDesc}.`,
     `Tool input: ${inputSummary}`,
+    tokenLine,
     '',
     `Is this tool call likely still working, or is it hung/frozen?`,
     'Consider: network latency, server response times, anti-bot protections, large page sizes, complex operations.',
+    'IMPORTANT: If tokens were active recently (< 60s ago), the process is likely still alive and processing — strongly favor WORKING.',
     '',
     'Respond in EXACTLY this format (3 lines, no extra text):',
     'VERDICT: WORKING or STALLED',
@@ -305,6 +325,10 @@ function buildAssessmentPrompt(ctx: StallContext): string {
     ? `${ctx.originalPrompt.slice(0, 500)}...`
     : ctx.originalPrompt;
 
+  const tokenLine = ctx.tokenSilenceMs !== undefined
+    ? `Token activity: last token event ${Math.round(ctx.tokenSilenceMs / 1000)}s ago (tokens flowing = process alive)`
+    : 'Token activity: no token events observed';
+
   return [
     'You are a process health monitor. A Claude Code subprocess has been silent (no stdout) and you must determine if it is working or stalled.',
     '',
@@ -314,6 +338,7 @@ function buildAssessmentPrompt(ctx: StallContext): string {
     ctx.lastToolInputSummary ? `Last tool input: ${ctx.lastToolInputSummary}` : '',
     `Pending tool calls: ${ctx.pendingToolCount}`,
     `Total tool calls this session: ${ctx.totalToolCalls}`,
+    tokenLine,
     `Task being executed: ${promptPreview}`,
     '',
     'Respond in EXACTLY this format (3 lines, no extra text):',