attocode 0.2.3 → 0.2.5

package/dist/src/integrations/budget/loop-detector.js

@@ -0,0 +1,287 @@
+/**
+ * Loop Detector - Doom loop and pattern detection for the economics system.
+ *
+ * Extracted from economics.ts (Phase 3b restructuring).
+ *
+ * Handles:
+ * - Exact and fuzzy doom loop detection (same tool+args repeated)
+ * - Bash file-read normalization (cat/head/tail targeting same file)
+ * - Structural fingerprinting for near-identical calls
+ * - Test-fix cycle detection
+ * - Bash failure cascade detection
+ * - Summary loop detection (consecutive text-only turns)
+ */
+import { stableStringify } from '../context/context-engineering.js';
+// =============================================================================
+// CONSTANTS
+// =============================================================================
+/**
+ * Regex for common bash file-read commands (simple, no pipes/redirects).
+ * Captures the file path for normalized doom loop fingerprinting.
+ */
+const BASH_FILE_READ_RE = /^\s*(cat|head|tail|wc|less|more|file|stat|md5sum|sha256sum)\b(?:\s+-[^\s]+)*\s+((?:\/|\.\/|\.\.\/)[\w.\/\-@]+|[\w.\-@][\w.\/\-@]*)\s*$/;
+/** Detect bash commands that are doing file write operations (write/append/redirect/heredoc). */
+const BASH_FILE_WRITE_RE = /^\s*(cat|echo|printf)\b.*(?:>>?|<<)\s*/;
+/**
+ * Primary argument keys that identify the *target* of a tool call.
+ * Used for fuzzy doom loop detection -- ignoring secondary/optional args.
+ */
+const PRIMARY_KEYS = ['path', 'file_path', 'command', 'pattern', 'query', 'url', 'content', 'filename', 'offset', 'limit'];
+// =============================================================================
+// PROMPT TEMPLATES
+// =============================================================================
+/**
+ * Doom loop prompt - injected when same tool called repeatedly.
+ */
+export const DOOM_LOOP_PROMPT = (tool, count) => {
+    if (count >= 6) {
+        return `[System] CRITICAL: You've called ${tool} with the same arguments ${count} times. You are in a doom loop. You MUST:
+1. STOP calling ${tool} immediately
+2. Explain what you're stuck on
+3. Try a completely different approach
+Further identical calls will be rejected.`;
+    }
+    if (count >= 4) {
+        return `[System] WARNING: You've called ${tool} ${count} times with identical arguments. This is a stuck state.
+1. Try a DIFFERENT approach or tool
+2. If blocked, explain the blocker`;
+    }
+    return `[System] You've called ${tool} with the same arguments ${count} times. This indicates a stuck state. Either:
+1. Try a DIFFERENT approach or tool
+2. If blocked, explain what's preventing progress
+3. If the task is complete, say so explicitly`;
+};
+/**
+ * Global doom loop prompt - injected when the same tool call is repeated across multiple workers.
+ */
+export const GLOBAL_DOOM_LOOP_PROMPT = (tool, workerCount, totalCalls) => `[System] GLOBAL DOOM LOOP: ${totalCalls} calls to ${tool} across ${workerCount} workers. The entire swarm is stuck on this approach.
+1. Try a fundamentally different strategy
+2. Do NOT retry the same tool/parameters
+3. Consider whether the task goal itself needs re-evaluation`;
+/**
+ * Test-fix rethink prompt - injected after consecutive test failures.
+ */
+export const TEST_FIX_RETHINK_PROMPT = (failures) => `[System] You've had ${failures} consecutive test failures. Step back and rethink:
+1. Re-read the error messages carefully
+2. Consider whether your approach is fundamentally wrong
+3. Try a DIFFERENT fix strategy instead of iterating on the same one
+Do not retry the same fix. Try a new approach.`;
+/** Check whether a bash command is attempting file operations that should use dedicated tools. */
+export function isBashFileOperation(command) {
+    return BASH_FILE_READ_RE.test(command) || BASH_FILE_WRITE_RE.test(command) || /heredoc|EOF/i.test(command);
+}
+export const BASH_FAILURE_CASCADE_PROMPT = (failures, lastCommand) => {
+    const isFileOp = lastCommand && isBashFileOperation(lastCommand);
+    if (isFileOp) {
+        return `[System] ${failures} consecutive bash commands have failed trying to do file operations.
+STOP using bash for file operations. Use the correct tool:
+- To CREATE a file: write_file (not cat/echo with redirect)
+- To MODIFY a file: edit_file (not sed/awk)
+- To READ a file: read_file (not cat/head/tail)
+Switch to the correct tool NOW.`;
+    }
+    return `[System] ${failures} consecutive bash commands have failed. STOP and:
+1. Explain what you're trying to accomplish
+2. Try a DIFFERENT approach or tool
+3. Do not run another bash command with the same pattern`;
+};
+export const SUMMARY_LOOP_PROMPT = `[System] You've produced text-only responses without using tools. You should be DOING work, not summarizing it.
+Pick the most important remaining task and start working on it NOW using your tools (write_file, edit_file, bash, etc.).
+Do NOT output another status summary or task list.`;
+// =============================================================================
+// HELPER FUNCTIONS (exported for external use)
+// =============================================================================
+/**
+ * Extract success and output from a bash tool result.
+ * In production, bash results are objects `{ success, output, metadata }`.
+ * Tests may pass strings directly. This normalizes both.
+ */
+export function extractBashResult(result) {
+    if (result && typeof result === 'object') {
+        const obj = result;
+        return {
+            success: obj.success !== false,
+            output: typeof obj.output === 'string' ? obj.output : '',
+        };
+    }
+    if (typeof result === 'string') {
+        return { success: true, output: result };
+    }
+    return { success: true, output: '' };
+}
+/**
+ * Extract the file target from a simple bash file-read command.
+ * Returns null for complex commands (pipes, redirects, non-file-read commands).
+ * Used to normalize doom loop fingerprints across cat/head/tail/wc targeting the same file.
+ */
+export function extractBashFileTarget(command) {
+    if (/[|;&<>]/.test(command))
+        return null; // pipes/redirects = complex, skip
+    const match = command.match(BASH_FILE_READ_RE);
+    return match ? match[2] : null;
+}
+/**
+ * Compute a structural fingerprint for a tool call.
+ * Extracts only the primary argument (path, command, pattern, query) and ignores
+ * secondary arguments (encoding, timeout, flags). This catches near-identical calls
+ * that differ only in optional parameters.
+ */
+export function computeToolFingerprint(toolName, argsStr) {
+    try {
+        const args = JSON.parse(argsStr || '{}');
+        // W1: Normalize bash file-read commands so cat/head/tail/wc targeting the same file
+        // produce the same fingerprint, triggering doom loop detection.
+        if (toolName === 'bash' && typeof args.command === 'string') {
+            const fileTarget = extractBashFileTarget(args.command);
+            if (fileTarget)
+                return `bash:file_read:${fileTarget}`;
+        }
+        const primaryArgs = {};
+        for (const key of PRIMARY_KEYS) {
+            if (key in args) {
+                primaryArgs[key] = args[key];
+            }
+        }
+        // If no primary keys found, fall back to full args
+        if (Object.keys(primaryArgs).length === 0) {
+            return `${toolName}:${stableStringify(args)}`;
+        }
+        return `${toolName}:${stableStringify(primaryArgs)}`;
+    }
+    catch {
+        // If args can't be parsed, use raw string
+        return `${toolName}:${argsStr}`;
+    }
+}
+/**
+ * LoopDetector handles doom loop detection and pattern-based stuck state identification.
+ *
+ * Two-tier detection:
+ * 1. Exact match: same tool+args string (threshold: 3 by default)
+ * 2. Fuzzy match: same tool + same primary args, ignoring optional params (threshold: 4 by default)
+ */
+export class LoopDetector {
+    loopState;
+    constructor(tuning) {
+        this.loopState = {
+            doomLoopDetected: false,
+            lastTool: null,
+            consecutiveCount: 0,
+            threshold: tuning?.doomLoopThreshold ?? 3,
+            fuzzyThreshold: tuning?.doomLoopFuzzyThreshold ?? (tuning?.doomLoopThreshold ? tuning.doomLoopThreshold + 1 : 4),
+            lastWarningTime: 0,
+        };
+    }
+    /**
+     * Update doom loop detection state given recent tool calls.
+     * Returns true if a NEW doom loop was just detected (first time).
+     */
+    updateDoomLoopState(toolName, argsStr, recentCalls) {
+        const currentCall = `${toolName}:${argsStr}`;
+        // === EXACT MATCH: Count consecutive identical calls from the end ===
+        let consecutiveCount = 0;
+        for (let i = recentCalls.length - 1; i >= 0; i--) {
+            const call = recentCalls[i];
+            if (`${call.tool}:${call.args}` === currentCall) {
+                consecutiveCount++;
+            }
+            else {
+                break;
+            }
+        }
+        // === FUZZY MATCH: Catches near-identical calls that differ only in optional params ===
+        // Only check if exact match didn't already trigger
+        if (consecutiveCount < this.loopState.threshold) {
+            const currentFingerprint = computeToolFingerprint(toolName, argsStr);
+            let fuzzyCount = 0;
+            for (let i = recentCalls.length - 1; i >= 0; i--) {
+                const call = recentCalls[i];
+                const callFingerprint = computeToolFingerprint(call.tool, call.args);
+                if (callFingerprint === currentFingerprint) {
+                    fuzzyCount++;
+                }
+                else {
+                    break;
+                }
+            }
+            // Use fuzzy count if it exceeds the fuzzy threshold
+            if (fuzzyCount >= this.loopState.fuzzyThreshold) {
+                consecutiveCount = Math.max(consecutiveCount, fuzzyCount);
+            }
+        }
+        this.loopState.consecutiveCount = consecutiveCount;
+        this.loopState.lastTool = toolName;
+        // Detect doom loop when threshold reached
+        const wasDoomLoop = this.loopState.doomLoopDetected;
+        this.loopState.doomLoopDetected = consecutiveCount >= this.loopState.threshold;
+        // Return true when doom loop first detected (not on every check)
+        return this.loopState.doomLoopDetected && !wasDoomLoop;
+    }
+    /**
+     * Get the current loop detection state (copy).
+     */
+    getState() {
+        return { ...this.loopState };
+    }
+    /**
+     * Whether a doom loop is currently detected.
+     */
+    get isDoomLoop() {
+        return this.loopState.doomLoopDetected;
+    }
+    /**
+     * The tool that is currently being repeated.
+     */
+    get lastTool() {
+        return this.loopState.lastTool;
+    }
+    /**
+     * How many consecutive times the same call has been made.
+     */
+    get consecutiveCount() {
+        return this.loopState.consecutiveCount;
+    }
+    /**
+     * Reset the loop detection state (preserves tuning thresholds).
+     */
+    reset(tuning) {
+        this.loopState = {
+            doomLoopDetected: false,
+            lastTool: null,
+            consecutiveCount: 0,
+            threshold: tuning?.doomLoopThreshold ?? 3,
+            fuzzyThreshold: tuning?.doomLoopFuzzyThreshold ?? (tuning?.doomLoopThreshold ? tuning.doomLoopThreshold + 1 : 4),
+            lastWarningTime: 0,
+        };
+    }
+    /**
+     * Check if recent tool calls indicate a stuck state (same call 3x in a row).
+     */
+    isStuckByRepetition(recentCalls) {
+        if (recentCalls.length >= 3) {
+            const last3 = recentCalls.slice(-3);
+            const unique = new Set(last3.map(tc => `${tc.tool}:${tc.args}`));
+            if (unique.size === 1) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Extract the last bash command from recent tool calls (for remediation prompts).
+     */
+    extractLastBashCommand(recentCalls) {
+        for (let i = recentCalls.length - 1; i >= 0; i--) {
+            if (recentCalls[i].tool === 'bash') {
+                try {
+                    const parsed = JSON.parse(recentCalls[i].args);
+                    return parsed.command;
+                }
+                catch { /* ignore parse errors */ }
+                break;
+            }
+        }
+        return undefined;
+    }
+}
+//# sourceMappingURL=loop-detector.js.map

package/dist/src/integrations/budget/loop-detector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-detector.js","sourceRoot":"","sources":["../../../../src/integrations/budget/loop-detector.ts"],"names":[],"mappings":"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"}

package/dist/src/integrations/budget/phase-tracker.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Phase Tracker - Phase transitions and nudge generation for the economics system.
+ *
+ * Extracted from economics.ts (Phase 3b restructuring).
+ *
+ * Handles:
+ * - Phase state management (exploring -> planning -> acting -> verifying)
+ * - Phase transition triggers
+ * - Exploration saturation detection
+ * - Test outcome parsing (pass/fail tracking)
+ * - Nudge prompt generation for exploration budget, verification reserve
+ */
+import type { PhaseState, EconomicsTuning, EconomicsEvent } from './economics.js';
+/**
+ * Exploration saturation prompt - gentle nudge to start making edits.
+ */
+export declare const EXPLORATION_NUDGE_PROMPT: (filesRead: number, iterations: number) => string;
+/**
+ * Phase budget exploration exceeded prompt.
+ */
+export declare const EXPLORATION_BUDGET_EXCEEDED_PROMPT: (pct: number) => string;
+/**
+ * Phase budget verification reserve prompt.
+ */
+export declare const VERIFICATION_RESERVE_PROMPT = "[System] You are running low on iterations. Run your tests NOW to verify your changes.\nDo not make more edits until you've confirmed whether the current fix works.";
+/**
+ * Callback for emitting economics events from the phase tracker.
+ */
+export type PhaseEventEmitter = (event: EconomicsEvent) => void;
+/**
+ * PhaseTracker manages execution phase state and transitions.
+ *
+ * Phases: exploring -> planning -> acting -> verifying
+ *
+ * Provides:
+ * - Automatic phase transitions based on tool calls (first edit -> acting, tests after edits -> verifying)
+ * - Exploration saturation detection (too many files read without edits)
+ * - Test outcome tracking (consecutive failures, test-fix cycles)
+ * - Bash failure cascade tracking
+ * - Summary loop detection (consecutive text-only turns)
+ */
+export declare class PhaseTracker {
+    private state;
+    private tuning;
+    private emit;
+    constructor(tuning: EconomicsTuning | undefined, emit: PhaseEventEmitter);
+    /**
+     * Create the initial phase state.
+     */
+    static createInitialState(): PhaseState;
+    /**
+     * Record a text-only turn (LLM response with no tool calls).
+     * Increments the consecutive text-only turn counter for summary-loop detection.
+     */
+    recordTextOnlyTurn(): void;
+    /**
+     * Called on every tool call to reset text-only counter and update phase iteration.
+     */
+    onToolCall(): void;
+    /**
+     * Track a file read operation and return whether it was a new file.
+     */
+    trackFileRead(path: string): boolean;
+    /**
+     * Track a search operation.
+     */
+    trackSearch(query: string): void;
+    /**
+     * Track a file modification and trigger phase transition if needed.
+     */
+    trackFileModified(path: string): void;
+    /**
+     * Track a bash command execution result.
+     */
+    trackBashResult(command: string, success: boolean, output: string): void;
+    /**
+     * Check for exploration saturation (reading too many files without action).
+     */
+    checkExplorationSaturation(): void;
+    /**
+     * Get a serializable snapshot of the phase state (for getPhaseState() API).
+     */
+    getSnapshot(): {
+        phase: string;
+        uniqueFilesRead: number;
+        uniqueSearches: number;
+        filesModified: number;
+        testsRun: number;
+        shouldTransition: boolean;
+        iterationsInPhase: number;
+        lastTestPassed: boolean | null;
+        consecutiveTestFailures: number;
+        inTestFixCycle: boolean;
+        consecutiveBashFailures: number;
+    };
+    /**
+     * Direct access to the raw phase state (for internal economics manager use).
+     */
+    get rawState(): PhaseState;
+    /**
+     * Reset the phase tracker to initial state.
+     */
+    reset(): void;
+    /**
+     * Transition to a new phase.
+     */
+    private transitionPhase;
+    /**
+     * Parse test outcome from bash command output.
+     * Updates test tracking fields.
+     */
+    private parseTestOutcome;
+}
+//# sourceMappingURL=phase-tracker.d.ts.map

package/dist/src/integrations/budget/phase-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase-tracker.d.ts","sourceRoot":"","sources":["../../../../src/integrations/budget/phase-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,eAAe,EAAE,cAAc,EAAqB,MAAM,gBAAgB,CAAC;AAMrG;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,WAAW,MAAM,EAAE,YAAY,MAAM,WAIF,CAAC;AAE7E;;GAEG;AACH,eAAO,MAAM,kCAAkC,GAAI,KAAK,MAAM,WAEH,CAAC;AAE5D;;GAEG;AACH,eAAO,MAAM,2BAA2B,yKAEqC,CAAC;AAM9E;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,IAAI,CAAoB;gBAEpB,MAAM,EAAE,eAAe,GAAG,SAAS,EAAE,IAAI,EAAE,iBAAiB;IAMxE;;OAEG;IACH,MAAM,CAAC,kBAAkB,IAAI,UAAU;IAmBvC;;;OAGG;IACH,kBAAkB,IAAI,IAAI;IAI1B;;OAEG;IACH,UAAU,IAAI,IAAI;IAUlB;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IASpC;;OAEG;IACH,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIhC;;OAEG;IACH,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAQrC;;OAEG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAqBxE;;OAEG;IACH,0BAA0B,IAAI,IAAI;IAoClC;;OAEG;IACH,WAAW,IAAI;QACb,KAAK,EAAE,MAAM,CAAC;QACd,eAAe,EAAE,MAAM,CAAC;QACxB,cAAc,EAAE,MAAM,CAAC;QACvB,aAAa,EAAE,MAAM,CAAC;QACtB,QAAQ,EAAE,MAAM,CAAC;QACjB,gBAAgB,EAAE,OAAO,CAAC;QAC1B,iBAAiB,EAAE,MAAM,CAAC;QAC1B,cAAc,EAAE,OAAO,GAAG,IAAI,CAAC;QAC/B,uBAAuB,EAAE,MAAM,CAAC;QAChC,cAAc,EAAE,OAAO,CAAC;QACxB,uBAAuB,EAAE,MAAM,CAAC;KACjC;IAgBD;;OAEG;IACH,IAAI,QAAQ,IAAI,UAAU,CAEzB;IAED;;OAEG;IACH,KAAK,IAAI,IAAI;IAQb;;OAEG;IACH,OAAO,CAAC,eAAe;IAqBvB;;;OAGG;IACH,OAAO,CAAC,gBAAgB;CAyBzB"}

package/dist/src/integrations/budget/phase-tracker.js

@@ -0,0 +1,262 @@
+/**
+ * Phase Tracker - Phase transitions and nudge generation for the economics system.
+ *
+ * Extracted from economics.ts (Phase 3b restructuring).
+ *
+ * Handles:
+ * - Phase state management (exploring -> planning -> acting -> verifying)
+ * - Phase transition triggers
+ * - Exploration saturation detection
+ * - Test outcome parsing (pass/fail tracking)
+ * - Nudge prompt generation for exploration budget, verification reserve
+ */
+// =============================================================================
+// PROMPT TEMPLATES
+// =============================================================================
+/**
+ * Exploration saturation prompt - gentle nudge to start making edits.
+ */
+export const EXPLORATION_NUDGE_PROMPT = (filesRead, iterations) => `[System] You've read ${filesRead} files across ${iterations} iterations. If you understand the issue:
+- Make the code changes now
+- Run tests to verify
+If you're still gathering context, briefly explain what you're looking for.`;
+/**
+ * Phase budget exploration exceeded prompt.
+ */
+export const EXPLORATION_BUDGET_EXCEEDED_PROMPT = (pct) => `[System] You've spent ${pct}% of your iterations in exploration. Start making edits NOW.
+Do not read more files. Use what you know to make the fix.`;
+/**
+ * Phase budget verification reserve prompt.
+ */
+export const VERIFICATION_RESERVE_PROMPT = `[System] You are running low on iterations. Run your tests NOW to verify your changes.
+Do not make more edits until you've confirmed whether the current fix works.`;
+/**
+ * PhaseTracker manages execution phase state and transitions.
+ *
+ * Phases: exploring -> planning -> acting -> verifying
+ *
+ * Provides:
+ * - Automatic phase transitions based on tool calls (first edit -> acting, tests after edits -> verifying)
+ * - Exploration saturation detection (too many files read without edits)
+ * - Test outcome tracking (consecutive failures, test-fix cycles)
+ * - Bash failure cascade tracking
+ * - Summary loop detection (consecutive text-only turns)
+ */
+export class PhaseTracker {
+    state;
+    tuning;
+    emit;
+    constructor(tuning, emit) {
+        this.tuning = tuning;
+        this.emit = emit;
+        this.state = PhaseTracker.createInitialState();
+    }
+    /**
+     * Create the initial phase state.
+     */
+    static createInitialState() {
+        return {
+            phase: 'exploring',
+            explorationStartIteration: 0,
+            uniqueFilesRead: new Set(),
+            uniqueSearches: new Set(),
+            filesModified: new Set(),
+            testsRun: 0,
+            shouldTransition: false,
+            iterationsInPhase: 0,
+            recentNewFiles: 0,
+            lastTestPassed: null,
+            consecutiveTestFailures: 0,
+            inTestFixCycle: false,
+            consecutiveBashFailures: 0,
+            consecutiveTextOnlyTurns: 0,
+        };
+    }
+    /**
+     * Record a text-only turn (LLM response with no tool calls).
+     * Increments the consecutive text-only turn counter for summary-loop detection.
+     */
+    recordTextOnlyTurn() {
+        this.state.consecutiveTextOnlyTurns++;
+    }
+    /**
+     * Called on every tool call to reset text-only counter and update phase iteration.
+     */
+    onToolCall() {
+        this.state.consecutiveTextOnlyTurns = 0;
+        this.state.iterationsInPhase++;
+        // Reset recentNewFiles counter every 3 iterations for diminishing returns check
+        if (this.state.iterationsInPhase % 3 === 0) {
+            this.state.recentNewFiles = 0;
+        }
+    }
+    /**
+     * Track a file read operation and return whether it was a new file.
+     */
+    trackFileRead(path) {
+        const isNew = !this.state.uniqueFilesRead.has(path);
+        this.state.uniqueFilesRead.add(path);
+        if (isNew) {
+            this.state.recentNewFiles++;
+        }
+        return isNew;
+    }
+    /**
+     * Track a search operation.
+     */
+    trackSearch(query) {
+        this.state.uniqueSearches.add(query);
+    }
+    /**
+     * Track a file modification and trigger phase transition if needed.
+     */
+    trackFileModified(path) {
+        this.state.filesModified.add(path);
+        // Transition to acting phase when first edit is made
+        if (this.state.phase === 'exploring' || this.state.phase === 'planning') {
+            this.transitionPhase('acting', 'First file edit made');
+        }
+    }
+    /**
+     * Track a bash command execution result.
+     */
+    trackBashResult(command, success, output) {
+        // Track consecutive bash failures
+        if (!success) {
+            this.state.consecutiveBashFailures++;
+        }
+        else {
+            this.state.consecutiveBashFailures = 0;
+        }
+        // Detect test runs and track outcomes
+        if (command.includes('test') || command.includes('pytest') || command.includes('npm test') || command.includes('jest')) {
+            this.state.testsRun++;
+            // Transition to verifying phase when tests are run after edits
+            if (this.state.phase === 'acting' && this.state.filesModified.size > 0) {
+                this.transitionPhase('verifying', 'Tests run after edits');
+            }
+            if (output) {
+                this.parseTestOutcome(command, output);
+            }
+        }
+    }
+    /**
+     * Check for exploration saturation (reading too many files without action).
+     */
+    checkExplorationSaturation() {
+        const { phase, uniqueFilesRead, iterationsInPhase, recentNewFiles, filesModified } = this.state;
+        // Only check during exploration phase
+        if (phase !== 'exploring') {
+            this.state.shouldTransition = false;
+            return;
+        }
+        // After N+ unique files without edits, suggest transition (configurable, default: 10)
+        const fileThreshold = this.tuning?.explorationFileThreshold ?? 10;
+        if (uniqueFilesRead.size >= fileThreshold && filesModified.size === 0) {
+            this.state.shouldTransition = true;
+            this.emit({
+                type: 'exploration.saturation',
+                filesRead: uniqueFilesRead.size,
+                iterations: iterationsInPhase,
+            });
+            return;
+        }
+        // After N+ iterations in exploration with diminishing returns (configurable, default: 15)
+        const iterThreshold = this.tuning?.explorationIterThreshold ?? 15;
+        if (iterationsInPhase >= iterThreshold && recentNewFiles < 2 && filesModified.size === 0) {
+            this.state.shouldTransition = true;
+            this.emit({
+                type: 'exploration.saturation',
+                filesRead: uniqueFilesRead.size,
+                iterations: iterationsInPhase,
+            });
+            return;
+        }
+        this.state.shouldTransition = false;
+    }
+    /**
+     * Get a serializable snapshot of the phase state (for getPhaseState() API).
+     */
+    getSnapshot() {
+        return {
+            phase: this.state.phase,
+            uniqueFilesRead: this.state.uniqueFilesRead.size,
+            uniqueSearches: this.state.uniqueSearches.size,
+            filesModified: this.state.filesModified.size,
+            testsRun: this.state.testsRun,
+            shouldTransition: this.state.shouldTransition,
+            iterationsInPhase: this.state.iterationsInPhase,
+            lastTestPassed: this.state.lastTestPassed,
+            consecutiveTestFailures: this.state.consecutiveTestFailures,
+            inTestFixCycle: this.state.inTestFixCycle,
+            consecutiveBashFailures: this.state.consecutiveBashFailures,
+        };
+    }
+    /**
+     * Direct access to the raw phase state (for internal economics manager use).
+     */
+    get rawState() {
+        return this.state;
+    }
+    /**
+     * Reset the phase tracker to initial state.
+     */
+    reset() {
+        this.state = PhaseTracker.createInitialState();
+    }
+    // ---------------------------------------------------------------------------
+    // PRIVATE METHODS
+    // ---------------------------------------------------------------------------
+    /**
+     * Transition to a new phase.
+     */
+    transitionPhase(newPhase, reason) {
+        const oldPhase = this.state.phase;
+        if (oldPhase === newPhase)
+            return;
+        this.emit({
+            type: 'phase.transition',
+            from: oldPhase,
+            to: newPhase,
+            reason,
+        });
+        this.state.phase = newPhase;
+        this.state.iterationsInPhase = 0;
+        this.state.recentNewFiles = 0;
+        if (newPhase === 'exploring') {
+            // explorationStartIteration is set by the caller (economics manager)
+            // since it knows the current iteration count
+        }
+    }
+    /**
+     * Parse test outcome from bash command output.
+     * Updates test tracking fields.
+     */
+    parseTestOutcome(_command, output) {
+        if (!output)
+            return;
+        // Detect pass/fail from pytest-style output
+        const hasPassed = /(\d+)\s+passed/.test(output) || output.includes('PASSED');
+        const hasFailed = /(\d+)\s+failed/.test(output) || output.includes('FAILED') || output.includes('ERROR');
+        if (hasFailed && !hasPassed) {
+            // Pure failure
+            this.state.lastTestPassed = false;
+            this.state.consecutiveTestFailures++;
+            this.state.inTestFixCycle = true;
+        }
+        else if (hasPassed && !hasFailed) {
+            // Pure pass
+            this.state.lastTestPassed = true;
+            this.state.consecutiveTestFailures = 0;
+            this.state.inTestFixCycle = false;
+        }
+        else if (hasPassed && hasFailed) {
+            // Mixed - some passed, some failed
+            this.state.lastTestPassed = false;
+            this.state.consecutiveTestFailures++;
+            this.state.inTestFixCycle = true;
+        }
+        // If no clear signal, don't update
+    }
+}
+//# sourceMappingURL=phase-tracker.js.map