mstro-app 0.4.38 → 0.4.43

package/server/cli/headless/resilient-runner.ts

@@ -0,0 +1,354 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Resilient Runner
+ *
+ * Wraps HeadlessRunner with composable retry strategies for tool timeouts,
+ * signal crashes, context loss, and premature completions. Configurable via
+ * policy levels: FULL (all strategies + best-result selection), STANDARD
+ * (basic retry without context-loss detection), or NONE (single attempt).
+ */
+
+import { hlog, runWithFileLogger } from './headless-logger.js';
+import {
+  createRetryState,
+  isResponseAbandoned,
+  type RetryConfig,
+  type RetryDecision,
+  type RetryState,
+  scoreResult,
+  tryContextLoss,
+  tryPrematureCompletion,
+  trySignalCrash,
+  tryToolTimeout,
+} from './retry-strategies.js';
+import { HeadlessRunner } from './runner.js';
+import { assessBestResult } from './stall-assessor.js';
+import type { ExecutionCheckpoint, SessionResult, ToolUseEvent } from './types.js';
+
+export type RetryPolicy = 'FULL' | 'STANDARD' | 'NONE';
+
+export interface ResilientRunnerConfig {
+  workingDir: string;
+  prompt: string;
+
+  policy?: RetryPolicy;
+  maxRetries?: number;
+
+  stallWarningMs?: number;
+  stallKillMs?: number;
+  stallHardCapMs?: number;
+  stallMaxExtensions?: number;
+
+  outputCallback?: (text: string) => void;
+  thinkingCallback?: (text: string) => void;
+  toolUseCallback?: (event: ToolUseEvent) => void;
+  tokenUsageCallback?: (usage: { inputTokens: number; outputTokens: number }) => void;
+
+  logLabel?: string;
+  logDir?: string;
+
+  abortSignal?: AbortSignal;
+  verbose?: boolean;
+  model?: string;
+  extraEnv?: Record<string, string>;
+
+  maxAutoContinues?: number;
+
+  onRetry?: (info: { retryNumber: number; maxRetries: number; path: string; reason: string }) => void;
+}
+
+function resolveRetryConfig(policy: RetryPolicy, verbose: boolean): RetryConfig {
+  switch (policy) {
+    case 'FULL':
+      return { enableContextLossDetection: true, enableBestResultSelection: true, verbose };
+    case 'STANDARD':
+      return { enableContextLossDetection: false, enableBestResultSelection: false, verbose };
+    case 'NONE':
+      return { enableContextLossDetection: false, enableBestResultSelection: false, verbose };
+  }
+}
+
+function wireAbortSignal(runner: HeadlessRunner, abortSignal?: AbortSignal): (() => void) | null {
+  if (!abortSignal) return null;
+  const handler = () => { runner.cleanup(); };
+  abortSignal.addEventListener('abort', handler, { once: true });
+  return () => abortSignal.removeEventListener('abort', handler);
+}
+
+function abortedFallback(bestResult: SessionResult | null): SessionResult {
+  return bestResult ?? {
+    completed: false,
+    needsHandoff: false,
+    totalTokens: 0,
+    sessionId: '',
+    error: 'Execution stopped by user',
+  };
+}
+
+function buildResultSummary(r: SessionResult): {
+  successfulToolCalls: number;
+  responseLength: number;
+  hasThinking: boolean;
+  responseTail: string;
+} {
+  return {
+    successfulToolCalls: r.toolUseHistory?.filter(t => t.result !== undefined && !t.isError).length ?? 0,
+    responseLength: r.assistantResponse?.length ?? 0,
+    hasThinking: !!r.thinkingOutput,
+    responseTail: (r.assistantResponse ?? '').slice(-500),
+  };
+}
+
+export class ResilientRunner {
+  private readonly config: ResilientRunnerConfig;
+
+  constructor(config: ResilientRunnerConfig) {
+    this.config = config;
+  }
+
+  async run(): Promise<SessionResult> {
+    const { logLabel, logDir } = this.config;
+    if (logLabel) {
+      return runWithFileLogger(logLabel, () => this.execute(), logDir);
+    }
+    return this.execute();
+  }
+
+  private async execute(): Promise<SessionResult> {
+    const policy = this.config.policy ?? 'STANDARD';
+    const maxRetries = this.config.maxRetries ?? 3;
+    const verbose = this.config.verbose ?? true;
+    const maxAutoContinues = this.config.maxAutoContinues ?? (policy === 'NONE' ? 0 : 1);
+    const retryConfig = resolveRetryConfig(policy, verbose);
+
+    if (policy === 'NONE') {
+      return this.runSingle(this.config.prompt, false, undefined);
+    }
+
+    const state = createRetryState(this.config.prompt, maxRetries);
+    const loopResult = await this.retryLoop(state, retryConfig, policy, maxRetries);
+
+    let result: SessionResult;
+    if (retryConfig.enableBestResultSelection && state.retryNumber > 0 && state.bestResult && loopResult) {
+      result = await this.selectBestResult(state.bestResult, loopResult, this.config.prompt);
+    } else {
+      result = loopResult ?? abortedFallback(state.bestResult);
+    }
+
+    return this.autoContinue(result, retryConfig, policy, maxRetries, maxAutoContinues);
+  }
+
+  private async retryLoop(
+    state: RetryState,
+    retryConfig: RetryConfig,
+    policy: RetryPolicy,
+    maxRetries: number,
+    initialPrompt?: string,
+    initialResumeSessionId?: string,
+  ): Promise<SessionResult | undefined> {
+    let lastResult: SessionResult | undefined;
+    let currentPrompt = initialPrompt ?? this.config.prompt;
+    let resumeSessionId = initialResumeSessionId;
+    let useResume = !!initialResumeSessionId;
+
+    while (state.retryNumber <= maxRetries) {
+      if (this.config.abortSignal?.aborted) return undefined;
+
+      state.checkpoint = null;
+      const result = await this.runAttempt(currentPrompt, useResume, resumeSessionId, state);
+      if (this.config.abortSignal?.aborted) return state.bestResult ?? result;
+
+      if (!state.bestResult || scoreResult(result) > scoreResult(state.bestResult)) {
+        state.bestResult = result;
+      }
+      lastResult = result;
+
+      const decision = await this.evaluateStrategies(result, state, retryConfig, policy);
+      if (!decision) break;
+
+      state.checkpoint = null;
+      currentPrompt = decision.nextPrompt;
+      resumeSessionId = decision.resumeSessionId;
+      useResume = decision.useResume;
+
+      hlog(`[RESILIENT] Retry ${state.retryNumber}/${maxRetries}: ${decision.path} — ${decision.reason}`);
+      this.config.onRetry?.({
+        retryNumber: state.retryNumber,
+        maxRetries,
+        path: decision.path,
+        reason: decision.reason,
+      });
+    }
+
+    return lastResult;
+  }
+
+  private async runAttempt(
+    prompt: string,
+    useResume: boolean,
+    resumeSessionId: string | undefined,
+    state: RetryState,
+  ): Promise<SessionResult> {
+    const runner = this.createHeadlessRunner(prompt, useResume, resumeSessionId, state);
+    const removeAbortListener = wireAbortSignal(runner, this.config.abortSignal);
+    const result = await runner.run();
+    removeAbortListener?.();
+    return result;
+  }
+
+  private createHeadlessRunner(
+    prompt: string,
+    continueSession: boolean,
+    claudeSessionId: string | undefined,
+    state: RetryState,
+  ): HeadlessRunner {
+    return new HeadlessRunner({
+      workingDir: this.config.workingDir,
+      directPrompt: prompt,
+      stallWarningMs: this.config.stallWarningMs,
+      stallKillMs: this.config.stallKillMs,
+      stallHardCapMs: this.config.stallHardCapMs,
+      stallMaxExtensions: this.config.stallMaxExtensions,
+      verbose: this.config.verbose ?? true,
+      continueSession: continueSession || undefined,
+      claudeSessionId,
+      outputCallback: this.config.outputCallback,
+      thinkingCallback: this.config.thinkingCallback,
+      toolUseCallback: this.config.toolUseCallback,
+      tokenUsageCallback: this.config.tokenUsageCallback,
+      model: this.config.model,
+      extraEnv: this.config.extraEnv,
+      onToolTimeout: (cp: ExecutionCheckpoint) => {
+        state.checkpoint = cp;
+      },
+    });
+  }
+
+  private async evaluateStrategies(
+    result: SessionResult,
+    state: RetryState,
+    retryConfig: RetryConfig,
+    policy: RetryPolicy,
+  ): Promise<RetryDecision | null> {
+    const toolTimeout = tryToolTimeout(result, state);
+    if (toolTimeout) return toolTimeout;
+
+    const signalCrash = trySignalCrash(result, state);
+    if (signalCrash) return signalCrash;
+
+    if (policy === 'FULL') {
+      const contextLoss = await tryContextLoss(result, state, retryConfig);
+      if (contextLoss) return contextLoss;
+    }
+
+    const premature = await tryPrematureCompletion(result, state, retryConfig);
+    if (premature) return premature;
+
+    return null;
+  }
+
+  private async selectBestResult(
+    bestResult: SessionResult,
+    finalResult: SessionResult,
+    originalPrompt: string,
+  ): Promise<SessionResult> {
+    if (bestResult === finalResult) return finalResult;
+
+    try {
+      const verdict = await assessBestResult(
+        {
+          originalPrompt,
+          resultA: buildResultSummary(bestResult),
+          resultB: buildResultSummary(finalResult),
+        },
+        process.env.CLAUDE_COMMAND || 'claude',
+        this.config.verbose ?? true,
+      );
+
+      hlog(`[RESILIENT] Best result selection: ${verdict.winner} — ${verdict.reason}`);
+      return verdict.winner === 'A' ? bestResult : finalResult;
+    } catch (err) {
+      hlog(`[RESILIENT] Best result assessment failed, using score: ${err}`);
+      return scoreResult(bestResult) >= scoreResult(finalResult) ? bestResult : finalResult;
+    }
+  }
+
+  private shouldAutoContinue(result: SessionResult): boolean {
+    if (!result.claudeSessionId) return false;
+
+    if (result.signalName) return true;
+
+    if (result.completed && !result.signalName && result.stopReason === 'end_turn') {
+      return isResponseAbandoned(result);
+    }
+
+    return false;
+  }
+
+  private async autoContinue(
+    initialResult: SessionResult,
+    retryConfig: RetryConfig,
+    policy: RetryPolicy,
+    maxRetries: number,
+    maxAutoContinues: number,
+  ): Promise<SessionResult> {
+    let result = initialResult;
+
+    for (let count = 0; count < maxAutoContinues; count++) {
+      if (this.config.abortSignal?.aborted) break;
+      if (!this.shouldAutoContinue(result)) break;
+
+      const reason = result.signalName ? 'Process stalled' : 'Response appears incomplete';
+      hlog(`[RESILIENT] Auto-continue ${count + 1}/${maxAutoContinues}: ${reason}`);
+      this.config.onRetry?.({
+        retryNumber: count + 1,
+        maxRetries: maxAutoContinues,
+        path: 'AutoContinue',
+        reason,
+      });
+
+      const continueState = createRetryState('continue', maxRetries);
+      const continueResult = await this.retryLoop(
+        continueState, retryConfig, policy, maxRetries,
+        'continue', result.claudeSessionId,
+      );
+
+      if (!continueResult) break;
+      result = scoreResult(continueResult) >= scoreResult(result) ? continueResult : result;
+    }
+
+    return result;
+  }
+
+  private async runSingle(
+    prompt: string,
+    continueSession: boolean,
+    claudeSessionId: string | undefined,
+  ): Promise<SessionResult> {
+    const runner = new HeadlessRunner({
+      workingDir: this.config.workingDir,
+      directPrompt: prompt,
+      stallWarningMs: this.config.stallWarningMs,
+      stallKillMs: this.config.stallKillMs,
+      stallHardCapMs: this.config.stallHardCapMs,
+      stallMaxExtensions: this.config.stallMaxExtensions,
+      verbose: this.config.verbose ?? true,
+      continueSession: continueSession || undefined,
+      claudeSessionId,
+      outputCallback: this.config.outputCallback,
+      thinkingCallback: this.config.thinkingCallback,
+      toolUseCallback: this.config.toolUseCallback,
+      tokenUsageCallback: this.config.tokenUsageCallback,
+      model: this.config.model,
+      extraEnv: this.config.extraEnv,
+    });
+
+    const removeAbortListener = wireAbortSignal(runner, this.config.abortSignal);
+    const result = await runner.run();
+    removeAbortListener?.();
+
+    return result;
+  }
+}

package/server/cli/headless/retry-strategies.ts

@@ -0,0 +1,330 @@
+// Copyright (c) 2025-present Mstro, Inc. All rights reserved.
+// Licensed under the MIT License. See LICENSE file for details.
+
+/**
+ * Shared retry strategy functions for headless execution.
+ *
+ * Pure decision functions that evaluate a SessionResult and RetryState,
+ * returning a RetryDecision when a retry should happen or null to skip.
+ * Used by both PM board execution (issue-retry) and Chat view (improvisation-retry).
+ */
+
+import {
+  buildFreshRecoveryPrompt,
+  buildResumeRetryPrompt,
+  buildRetryPrompt,
+  buildSignalCrashRecoveryPrompt,
+} from '../prompt-builders.js';
+import { hlog } from './headless-logger.js';
+import { assessContextLoss, assessPrematureCompletion } from './stall-assessor.js';
+import type { ExecutionCheckpoint, SessionResult } from './types.js';
+
+export interface ToolRecord {
+  toolName: string;
+  toolId: string;
+  toolInput: Record<string, unknown>;
+  result?: string;
+  isError?: boolean;
+  duration?: number;
+}
+
+export interface RetryState {
+  retryNumber: number;
+  maxRetries: number;
+  originalPrompt: string;
+  accumulatedToolResults: ToolRecord[];
+  timedOutTools: Array<{ toolName: string; input: Record<string, unknown>; timeoutMs: number }>;
+  checkpoint: ExecutionCheckpoint | null;
+  bestResult: SessionResult | null;
+}
+
+export interface RetryDecision {
+  nextPrompt: string;
+  useResume: boolean;
+  resumeSessionId?: string;
+  path: string;
+  reason: string;
+}
+
+export interface RetryConfig {
+  enableContextLossDetection: boolean;
+  enableBestResultSelection: boolean;
+  verbose: boolean;
+}
+
+const MAX_ACCUMULATED_RESULTS = 50;
+
+export function createRetryState(originalPrompt: string, maxRetries: number): RetryState {
+  return {
+    retryNumber: 0,
+    maxRetries,
+    originalPrompt,
+    accumulatedToolResults: [],
+    timedOutTools: [],
+    checkpoint: null,
+    bestResult: null,
+  };
+}
+
+export function accumulateToolResults(result: SessionResult, state: RetryState): void {
+  if (!result.toolUseHistory) return;
+  for (const t of result.toolUseHistory) {
+    if (t.result !== undefined) {
+      state.accumulatedToolResults.push({
+        toolName: t.toolName,
+        toolId: t.toolId,
+        toolInput: t.toolInput,
+        result: t.result,
+        isError: t.isError,
+        duration: t.duration,
+      });
+    }
+  }
+  if (state.accumulatedToolResults.length > MAX_ACCUMULATED_RESULTS) {
+    state.accumulatedToolResults = state.accumulatedToolResults.slice(-MAX_ACCUMULATED_RESULTS);
+  }
+}
+
+export function scoreResult(r: SessionResult): number {
+  const toolCount = r.toolUseHistory?.filter(t => t.result !== undefined && !t.isError).length ?? 0;
+  const responseLen = Math.min((r.assistantResponse?.length ?? 0) / 50, 100);
+  const hasThinking = r.thinkingOutput ? 20 : 0;
+  return toolCount * 10 + responseLen + hasThinking;
+}
+
+export function isResponseAbandoned(result: SessionResult): boolean {
+  const thinkingLen = result.thinkingOutput?.length ?? 0;
+  const responseLen = result.assistantResponse?.length ?? 0;
+  const toolCallsInResponse = result.toolUseHistory?.filter(t => t.result !== undefined).length ?? 0;
+
+  if (thinkingLen < 500 || responseLen > 1000) return false;
+  if (toolCallsInResponse > 0 && responseLen > 200) return false;
+
+  return thinkingLen >= responseLen * 3;
+}
+
+export function extractFinalTextBlock(response: string, maxLen: number): string {
+  const lastBreak = response.lastIndexOf('\n\n');
+  if (lastBreak !== -1 && response.length - lastBreak > 20) {
+    return response.slice(lastBreak + 2).slice(-maxLen);
+  }
+  return response.slice(-maxLen);
+}
+
+export function tryToolTimeout(_result: SessionResult, state: RetryState): RetryDecision | null {
+  if (!state.checkpoint || state.retryNumber >= state.maxRetries) return null;
+
+  const cp = state.checkpoint;
+  state.retryNumber++;
+
+  state.timedOutTools.push({
+    toolName: cp.hungTool.toolName,
+    input: cp.hungTool.input ?? {},
+    timeoutMs: cp.hungTool.timeoutMs,
+  });
+
+  const canResume = cp.inProgressTools.length === 0 && !!cp.claudeSessionId;
+  const reason = `${cp.hungTool.toolName} timed out after ${Math.round(cp.hungTool.timeoutMs / 1000)}s, ${cp.completedTools.length} tools completed, ${canResume ? 'resuming' : 'fresh start'}`;
+
+  hlog(`[RETRY] Tool timeout: ${reason} (retry ${state.retryNumber}/${state.maxRetries})`);
+
+  if (canResume) {
+    return {
+      nextPrompt: buildResumeRetryPrompt(cp, state.timedOutTools),
+      useResume: true,
+      resumeSessionId: cp.claudeSessionId,
+      path: 'ToolTimeout',
+      reason,
+    };
+  }
+
+  return {
+    nextPrompt: buildRetryPrompt(cp, state.originalPrompt, state.timedOutTools),
+    useResume: false,
+    path: 'ToolTimeout',
+    reason,
+  };
+}
+
+export function trySignalCrash(result: SessionResult, state: RetryState): RetryDecision | null {
+  const isSignalCrash = !!result.signalName;
+  const exitCodeSignal = !result.completed && !result.signalName && result.error?.match(/exited with code (1[2-9]\d|[2-9]\d{2})/);
+  if (!isSignalCrash && !exitCodeSignal) return null;
+  if (state.retryNumber >= state.maxRetries) return null;
+  if (state.checkpoint) return null;
+
+  accumulateToolResults(result, state);
+  state.retryNumber++;
+
+  const signalInfo = result.signalName || 'unknown signal';
+  const useResume = !!result.claudeSessionId && state.retryNumber === 1;
+  const reason = `Process killed (${signalInfo}), ${state.accumulatedToolResults.length} tools preserved, ${useResume ? 'resuming' : 'fresh start'}`;
+
+  hlog(`[RETRY] Signal crash: ${reason} (retry ${state.retryNumber}/${state.maxRetries})`);
+
+  if (useResume) {
+    return {
+      nextPrompt: buildSignalCrashRecoveryPrompt(state.originalPrompt, true),
+      useResume: true,
+      resumeSessionId: result.claudeSessionId,
+      path: 'SignalCrash',
+      reason,
+    };
+  }
+
+  return {
+    nextPrompt: buildSignalCrashRecoveryPrompt(state.originalPrompt, false, state.accumulatedToolResults),
+    useResume: false,
+    path: 'SignalCrash',
+    reason,
+  };
+}
+
+function detectContextLossHeuristic(result: SessionResult, verbose: boolean): boolean {
+  if (!result.assistantResponse || result.assistantResponse.trim().length === 0) {
+    if (verbose) hlog('[RETRY] Context loss heuristic: null/empty response');
+    return true;
+  }
+  if (result.resumeBufferedOutput !== undefined) {
+    if (verbose) hlog('[RETRY] Context loss heuristic: buffer never flushed (no thinking/tools)');
+    return true;
+  }
+  if (
+    (!result.toolUseHistory || result.toolUseHistory.length === 0) &&
+    !result.thinkingOutput &&
+    result.assistantResponse.length < 500
+  ) {
+    if (verbose) hlog('[RETRY] Context loss heuristic: no tools, no thinking, short response');
+    return true;
+  }
+  return false;
+}
+
+function computeEffectiveTimeouts(result: SessionResult): number {
+  const nativeTimeouts = result.nativeTimeoutCount ?? 0;
+  if (nativeTimeouts === 0) return 0;
+
+  const succeededIds = new Set<string>();
+  const allIds = new Set<string>();
+  for (const t of result.toolUseHistory ?? []) {
+    allIds.add(t.toolId);
+    if (t.result !== undefined) succeededIds.add(t.toolId);
+  }
+  const toolsWithoutResult = Array.from(allIds).filter(id => !succeededIds.has(id)).length;
+  return Math.max(nativeTimeouts, toolsWithoutResult);
+}
+
+async function detectContextLossViaHaiku(
+  result: SessionResult,
+  effectiveTimeouts: number,
+  verbose: boolean,
+): Promise<boolean> {
+  if (effectiveTimeouts === 0 || !result.assistantResponse) return false;
+
+  const writeToolNames = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit']);
+  const claudeCmd = process.env.CLAUDE_COMMAND || 'claude';
+  try {
+    const verdict = await assessContextLoss({
+      assistantResponse: result.assistantResponse,
+      effectiveTimeouts,
+      nativeTimeoutCount: result.nativeTimeoutCount ?? 0,
+      successfulToolCalls: result.toolUseHistory?.filter(t => t.result !== undefined && !t.isError).length ?? 0,
+      thinkingOutputLength: result.thinkingOutput?.length ?? 0,
+      hasSuccessfulWrite: result.toolUseHistory?.some(
+        t => writeToolNames.has(t.toolName) && t.result !== undefined && !t.isError
+      ) ?? false,
+    }, claudeCmd, verbose);
+    if (verbose) hlog(`[RETRY] Haiku context loss verdict: ${verdict.contextLost ? 'LOST' : 'OK'} — ${verdict.reason}`);
+    return verdict.contextLost;
+  } catch {
+    if (verbose) hlog('[RETRY] Haiku context loss assessment failed, assuming OK');
+    return false;
+  }
+}
+
+export async function tryContextLoss(
+  result: SessionResult,
+  state: RetryState,
+  config: RetryConfig,
+): Promise<RetryDecision | null> {
+  if (!config.enableContextLossDetection) return null;
+  if (state.checkpoint || state.retryNumber >= state.maxRetries) return null;
+
+  const heuristicLost = detectContextLossHeuristic(result, config.verbose);
+  const haikuLost = heuristicLost
+    ? false
+    : await detectContextLossViaHaiku(result, computeEffectiveTimeouts(result), config.verbose);
+
+  if (!heuristicLost && !haikuLost) return null;
+
+  accumulateToolResults(result, state);
+  state.retryNumber++;
+
+  const reason = `Context lost, ${state.accumulatedToolResults.length} tools preserved`;
+  hlog(`[RETRY] Context loss: ${reason} (retry ${state.retryNumber}/${state.maxRetries})`);
+
+  return {
+    nextPrompt: buildFreshRecoveryPrompt(state.originalPrompt, state.accumulatedToolResults, state.timedOutTools),
+    useResume: false,
+    path: 'ContextLoss',
+    reason,
+  };
+}
+
+async function isEndTurnIncomplete(result: SessionResult, verbose: boolean): Promise<boolean> {
+  if (isResponseAbandoned(result)) {
+    if (verbose) hlog('[RETRY] Response abandoned heuristic triggered');
+    return true;
+  }
+  if (!result.assistantResponse) return false;
+
+  const claudeCmd = process.env.CLAUDE_COMMAND || 'claude';
+  try {
+    const verdict = await assessPrematureCompletion({
+      responseTail: extractFinalTextBlock(result.assistantResponse, 800),
+      successfulToolCalls: result.toolUseHistory?.filter(t => t.result !== undefined && !t.isError).length ?? 0,
+      hasThinking: !!result.thinkingOutput,
+      responseLength: result.assistantResponse.length,
+    }, claudeCmd, verbose);
+    if (verbose) {
+      hlog(`[RETRY] Premature completion verdict: ${verdict.isIncomplete ? 'INCOMPLETE' : 'COMPLETE'} — ${verdict.reason}`);
+    }
+    return verdict.isIncomplete;
+  } catch {
+    if (verbose) hlog('[RETRY] Premature completion assessment failed, assuming complete');
+    return false;
+  }
+}
+
+function isPrematureCompletionCandidate(result: SessionResult, state: RetryState): boolean {
+  if (!result.completed || result.signalName || !result.stopReason) return false;
+  if (state.retryNumber >= state.maxRetries) return false;
+  if (state.checkpoint) return false;
+  if (!result.claudeSessionId) return false;
+  return result.stopReason === 'max_tokens' || result.stopReason === 'end_turn';
+}
+
+export async function tryPrematureCompletion(
+  result: SessionResult,
+  state: RetryState,
+  config: RetryConfig,
+): Promise<RetryDecision | null> {
+  if (!isPrematureCompletionCandidate(result, state)) return null;
+
+  const isMaxTokens = result.stopReason === 'max_tokens';
+
+  if (!isMaxTokens && !(await isEndTurnIncomplete(result, config.verbose))) return null;
+
+  state.retryNumber++;
+  const reason = isMaxTokens ? 'Output limit reached' : 'Task appears unfinished (AI assessment)';
+
+  hlog(`[RETRY] Premature completion: ${reason}, resuming session (retry ${state.retryNumber}/${state.maxRetries})`);
+
+  return {
+    nextPrompt: 'continue',
+    useResume: true,
+    resumeSessionId: result.claudeSessionId,
+    path: 'PrematureCompletion',
+    reason,
+  };
+}

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

@@ -239,6 +239,11 @@ export async function assessToolTimeout(
     Task: 'spawns a subagent that runs autonomously with its own tools',
     Agent: 'spawns a subagent that runs autonomously with its own tools',
     Bash: 'executes a shell command',
+    Write: 'writes file content that may be very large; content streams token-by-token through stdio before disk write',
+    Edit: 'applies string replacements to a file; streams through stdio protocol',
+    Read: 'reads file contents that may be very large; result streams through stdio protocol',
+    Grep: 'searches file contents with regex; large codebases produce large result streams',
+    Glob: 'finds files by pattern; large directory trees take time to scan',
   };
   const toolDesc = toolDescriptions[toolName] || `executes the ${toolName} tool`;