aicodeman 0.2.8

package/dist/ralph-tracker.d.ts

@@ -0,0 +1,1081 @@
+/**
+ * @fileoverview Ralph Tracker - Detects Ralph Wiggum loops, todos, and completion phrases
+ *
+ * This module parses terminal output from Claude Code sessions to detect:
+ * - Ralph Wiggum loop state (active, completion phrase, iteration count)
+ * - Todo list items from the TodoWrite tool
+ * - Completion phrases signaling loop completion
+ *
+ * The tracker is DISABLED by default and auto-enables when Ralph-related
+ * patterns are detected in the output stream, reducing overhead for
+ * sessions not using autonomous loops.
+ *
+ * @module ralph-tracker
+ */
+import { EventEmitter } from 'node:events';
+import { RalphTrackerState, RalphTodoItem, RalphStatusBlock, CircuitBreakerStatus, RalphTodoProgress, CompletionConfidence, PlanTaskStatus, TddPhase } from './types.js';
+/**
+ * Enhanced plan task with verification criteria, dependencies, and execution tracking.
+ * Supports TDD workflow, failure tracking, and plan versioning.
+ */
+export interface EnhancedPlanTask {
+    /** Unique identifier (e.g., "P0-001") */
+    id: string;
+    /** Task description */
+    content: string;
+    /** Criticality level */
+    priority: 'P0' | 'P1' | 'P2' | null;
+    /** How to verify completion */
+    verificationCriteria?: string;
+    /** Command to run for verification */
+    testCommand?: string;
+    /** IDs of tasks that must complete first */
+    dependencies: string[];
+    /** Current execution status */
+    status: PlanTaskStatus;
+    /** How many times attempted */
+    attempts: number;
+    /** Most recent failure reason */
+    lastError?: string;
+    /** Timestamp of completion */
+    completedAt?: number;
+    /** Plan version this belongs to */
+    version: number;
+    /** TDD phase category */
+    tddPhase?: TddPhase;
+    /** ID of paired test/impl task */
+    pairedWith?: string;
+    /** Estimated complexity */
+    complexity?: 'low' | 'medium' | 'high';
+    /** Checklist items for review tasks (tddPhase: 'review') */
+    reviewChecklist?: string[];
+}
+/** Checkpoint review data */
+export interface CheckpointReview {
+    iteration: number;
+    timestamp: number;
+    summary: {
+        total: number;
+        completed: number;
+        failed: number;
+        blocked: number;
+        pending: number;
+        inProgress: number;
+    };
+    stuckTasks: Array<{
+        id: string;
+        content: string;
+        attempts: number;
+        lastError?: string;
+    }>;
+    recommendations: string[];
+}
+/**
+ * Events emitted by RalphTracker
+ * @event loopUpdate - Fired when loop state changes (active, iteration, completion phrase)
+ * @event todoUpdate - Fired when todo list changes (items added, status changed)
+ * @event completionDetected - Fired when completion phrase is detected (task complete)
+ * @event enabled - Fired when tracker auto-enables due to Ralph pattern detection
+ * @event statusBlockDetected - Fired when a RALPH_STATUS block is parsed
+ * @event circuitBreakerUpdate - Fired when circuit breaker state changes
+ * @event exitGateMet - Fired when dual-condition exit gate is met
+ */
+export interface RalphTrackerEvents {
+    /** Emitted when loop state changes */
+    loopUpdate: (state: RalphTrackerState) => void;
+    /** Emitted when todo list is modified */
+    todoUpdate: (todos: RalphTodoItem[]) => void;
+    /** Emitted when completion phrase detected (loop finished) */
+    completionDetected: (phrase: string) => void;
+    /** Emitted when tracker auto-enables from disabled state */
+    enabled: () => void;
+    /** Emitted when a RALPH_STATUS block is parsed */
+    statusBlockDetected: (block: RalphStatusBlock) => void;
+    /** Emitted when circuit breaker state changes */
+    circuitBreakerUpdate: (status: CircuitBreakerStatus) => void;
+    /** Emitted when dual-condition exit gate is met (completion indicators >= 2 AND EXIT_SIGNAL: true) */
+    exitGateMet: (data: {
+        completionIndicators: number;
+        exitSignal: boolean;
+    }) => void;
+    /** Emitted when iteration count hasn't changed for an extended period (stall warning) */
+    iterationStallWarning: (data: {
+        iteration: number;
+        stallDurationMs: number;
+    }) => void;
+    /** Emitted when iteration count hasn't changed for critical period (stall critical) */
+    iterationStallCritical: (data: {
+        iteration: number;
+        stallDurationMs: number;
+    }) => void;
+    /** Emitted when a common/risky completion phrase is detected (P1-002) */
+    phraseValidationWarning: (data: {
+        phrase: string;
+        reason: 'common' | 'short' | 'numeric';
+        suggestedPhrase: string;
+    }) => void;
+}
+/**
+ * RalphTracker - Parses terminal output to detect Ralph Wiggum loops and todos
+ *
+ * This class monitors Claude Code session output to detect:
+ * 1. **Ralph Wiggum loop state** - Active loops, completion phrases, iteration counts
+ * 2. **Todo list items** - From TodoWrite tool in various formats
+ * 3. **Completion signals** - `<promise>PHRASE</promise>` tags
+ *
+ * ## Lifecycle
+ *
+ * The tracker is **DISABLED by default** and auto-enables when Ralph-related
+ * patterns are detected (e.g., /ralph-loop:ralph-loop, <promise>, todos).
+ * This reduces overhead for sessions not using autonomous loops.
+ *
+ * ## Completion Detection
+ *
+ * Uses occurrence-based detection to distinguish prompt from actual completion:
+ * - 1st occurrence of `<promise>X</promise>`: Stored as expected phrase (likely in prompt)
+ * - 2nd occurrence: Emits `completionDetected` event (actual completion)
+ * - If loop already active: Emits immediately on first occurrence
+ *
+ * ## Events
+ *
+ * - `loopUpdate` - Loop state changed (status, iteration, phrase)
+ * - `todoUpdate` - Todo list modified (add, status change)
+ * - `completionDetected` - Loop completion phrase detected
+ * - `enabled` - Tracker auto-enabled from disabled state
+ *
+ * @extends EventEmitter
+ * @example
+ * ```typescript
+ * const tracker = new RalphTracker();
+ * tracker.on('completionDetected', (phrase) => {
+ *   console.log('Loop completed with phrase:', phrase);
+ * });
+ * tracker.processTerminalData(ptyOutput);
+ * ```
+ */
+export declare class RalphTracker extends EventEmitter {
+    /** Current state of the detected loop */
+    private _loopState;
+    /** Map of todo items by ID for O(1) lookup */
+    private _todos;
+    /** Buffer for incomplete lines from terminal data */
+    private _lineBuffer;
+    /**
+     * Tracks occurrences of completion phrases.
+     * Used to distinguish prompt echo (1st) from actual completion (2nd+).
+     */
+    private _completionPhraseCount;
+    /** Timestamp of last cleanup check for throttling */
+    private _lastCleanupTime;
+    /** Debounce timer for todoUpdate events */
+    private _todoUpdateTimer;
+    /** Debounce timer for loopUpdate events */
+    private _loopUpdateTimer;
+    /** Flag indicating pending todoUpdate emission */
+    private _todoUpdatePending;
+    /** Flag indicating pending loopUpdate emission */
+    private _loopUpdatePending;
+    /** When true, prevents auto-enable on pattern detection */
+    private _autoEnableDisabled;
+    /** Maps task numbers from "✔ Task #N" format to their content for status updates */
+    private _taskNumberToContent;
+    /**
+     * Buffer for partial promise tags split across PTY chunks.
+     * Holds content after '<promise>' when closing tag hasn't arrived yet.
+     * Max 256 chars to prevent unbounded growth from malformed tags.
+     */
+    private _partialPromiseBuffer;
+    /** Maximum size of partial promise buffer */
+    private static readonly MAX_PARTIAL_PROMISE_SIZE;
+    /** Circuit breaker state tracking */
+    private _circuitBreaker;
+    /** Buffer for RALPH_STATUS block lines */
+    private _statusBlockBuffer;
+    /** Flag indicating we're inside a RALPH_STATUS block */
+    private _inStatusBlock;
+    /** Last parsed RALPH_STATUS block */
+    private _lastStatusBlock;
+    /** Count of completion indicators detected (for dual-condition exit) */
+    private _completionIndicators;
+    /** Whether dual-condition exit gate has been met */
+    private _exitGateMet;
+    /** Cumulative files modified across all iterations */
+    private _totalFilesModified;
+    /** Cumulative tasks completed across all iterations */
+    private _totalTasksCompleted;
+    /** Working directory for @fix_plan.md watching */
+    private _workingDir;
+    /** File watcher for @fix_plan.md */
+    private _fixPlanWatcher;
+    /** Error handler for FSWatcher (stored for cleanup to prevent memory leak) */
+    private _fixPlanWatcherErrorHandler;
+    /** Debounce timer for file change events */
+    private _fixPlanReloadTimer;
+    /** Path to the @fix_plan.md file being watched */
+    private _fixPlanPath;
+    /**
+     * When @fix_plan.md is active, treat it as the source of truth for todo status.
+     * This prevents output-based detection from overriding file-based status.
+     */
+    private get isFileAuthoritative();
+    /** Current version of the plan (incremented on changes) */
+    private _planVersion;
+    /** History of plan versions for rollback support */
+    private _planHistory;
+    /** Enhanced plan tasks with execution tracking */
+    private _planTasks;
+    /** Checkpoint intervals (iterations at which to trigger review) */
+    private _checkpointIterations;
+    /** Last checkpoint iteration */
+    private _lastCheckpointIteration;
+    /** Timestamp when iteration count last changed */
+    private _lastIterationChangeTime;
+    /** Last observed iteration count for stall detection */
+    private _lastObservedIteration;
+    /** Timer for iteration stall detection */
+    private _iterationStallTimer;
+    /** Iteration stall warning threshold (ms) - default 10 minutes */
+    private _iterationStallWarningMs;
+    /** Iteration stall critical threshold (ms) - default 20 minutes */
+    private _iterationStallCriticalMs;
+    /** Whether stall warning has been emitted */
+    private _iterationStallWarned;
+    /** Alternate completion phrases (P1-003: multi-phrase support) - Set for O(1) lookup */
+    private _alternateCompletionPhrases;
+    /** History of todo completion times (ms) for averaging */
+    private _completionTimes;
+    /** Maximum number of completion times to track */
+    private static readonly MAX_COMPLETION_TIMES;
+    /** Timestamp when todos started being tracked for this session */
+    private _todosStartedAt;
+    /** Map of todo ID to timestamp when it started (for duration tracking) */
+    private _todoStartTimes;
+    /**
+     * Creates a new RalphTracker instance.
+     * Starts in disabled state until Ralph patterns are detected.
+     */
+    constructor();
+    /**
+     * Add an alternate completion phrase (P1-003: multi-phrase support).
+     * Multiple phrases can trigger completion (useful for complex workflows).
+     * @param phrase - Additional phrase that can trigger completion
+     */
+    addAlternateCompletionPhrase(phrase: string): void;
+    /**
+     * Remove an alternate completion phrase.
+     * @param phrase - Phrase to remove
+     */
+    removeAlternateCompletionPhrase(phrase: string): void;
+    /**
+     * Check if a phrase matches any valid completion phrase (primary or alternate).
+     * @param phrase - Phrase to check
+     * @returns True if phrase matches any valid completion phrase
+     */
+    isValidCompletionPhrase(phrase: string): boolean;
+    /**
+     * Find which completion phrase (primary or alternate) matches the given phrase.
+     * @param phrase - Phrase to check
+     * @returns The matched canonical phrase, or null if no match
+     */
+    private findMatchingCompletionPhrase;
+    /**
+     * Prevent auto-enable from pattern detection.
+     * Use this when the user has explicitly disabled the Ralph tracker.
+     */
+    disableAutoEnable(): void;
+    /**
+     * Allow auto-enable from pattern detection.
+     */
+    enableAutoEnable(): void;
+    /**
+     * Whether auto-enable is disabled.
+     */
+    get autoEnableDisabled(): boolean;
+    /**
+     * Set the working directory and start watching @fix_plan.md.
+     * Automatically loads existing @fix_plan.md if present.
+     * @param workingDir - The session's working directory
+     */
+    setWorkingDir(workingDir: string): void;
+    /**
+     * Load @fix_plan.md from disk if it exists.
+     * Called on initialization and when file changes are detected.
+     */
+    loadFixPlanFromDisk(): Promise<number>;
+    /**
+     * Start watching @fix_plan.md for changes.
+     * Reloads todos when the file is modified.
+     */
+    private startWatchingFixPlan;
+    /**
+     * Handle @fix_plan.md file change with debouncing.
+     */
+    private handleFixPlanChange;
+    /**
+     * Stop watching @fix_plan.md.
+     */
+    stopWatchingFixPlan(): void;
+    /**
+     * Whether the tracker is enabled and actively monitoring output.
+     * Disabled by default; auto-enables when Ralph patterns detected.
+     * @returns True if tracker is processing terminal data
+     */
+    get enabled(): boolean;
+    /**
+     * Enable the tracker to start monitoring terminal output.
+     * Called automatically when Ralph patterns are detected.
+     * Emits 'enabled' event when transitioning from disabled state.
+     * @fires enabled
+     * @fires loopUpdate
+     */
+    enable(): void;
+    /**
+     * Disable the tracker to stop monitoring terminal output.
+     * Terminal data will be ignored until re-enabled.
+     * @fires loopUpdate
+     */
+    disable(): void;
+    /**
+     * Soft reset - clears state but keeps enabled status.
+     * Use when a new task/loop starts within the same session.
+     *
+     * Clears:
+     * - All todo items
+     * - Completion phrase tracking
+     * - Loop state (active, iterations)
+     * - Line buffer
+     *
+     * Preserves:
+     * - Enabled status
+     *
+     * @fires loopUpdate
+     * @fires todoUpdate
+     */
+    reset(): void;
+    /**
+     * Full reset - clears all state including enabled status.
+     * Use when session is closed or completely cleared.
+     * Returns tracker to initial disabled state.
+     * @fires loopUpdate
+     * @fires todoUpdate
+     */
+    fullReset(): void;
+    /**
+     * Clear all debounce timers.
+     * Called during reset/fullReset to prevent stale emissions.
+     */
+    private clearDebounceTimers;
+    /**
+     * Emit todoUpdate event with debouncing.
+     * Batches rapid consecutive calls to reduce UI jitter.
+     * The event fires after EVENT_DEBOUNCE_MS of inactivity.
+     */
+    private emitTodoUpdateDebounced;
+    /**
+     * Emit loopUpdate event with debouncing.
+     * Batches rapid consecutive calls to reduce UI jitter.
+     * The event fires after EVENT_DEBOUNCE_MS of inactivity.
+     */
+    private emitLoopUpdateDebounced;
+    /**
+     * Flush all pending debounced events immediately.
+     * Useful for testing or when immediate state sync is needed.
+     */
+    flushPendingEvents(): void;
+    /**
+     * Get a copy of the current loop state.
+     * @returns Shallow copy of loop state (safe to modify)
+     */
+    /**
+     * Start iteration stall detection timer.
+     * Should be called when the loop becomes active.
+     */
+    startIterationStallDetection(): void;
+    /**
+     * Stop iteration stall detection timer.
+     */
+    stopIterationStallDetection(): void;
+    /**
+     * Check for iteration stall and emit appropriate events.
+     */
+    private checkIterationStall;
+    /**
+     * Get iteration stall metrics for monitoring.
+     */
+    getIterationStallMetrics(): {
+        lastIterationChangeTime: number;
+        stallDurationMs: number;
+        warningThresholdMs: number;
+        criticalThresholdMs: number;
+        isWarned: boolean;
+        currentIteration: number;
+    };
+    /**
+     * Configure iteration stall thresholds.
+     * @param warningMs - Warning threshold in milliseconds
+     * @param criticalMs - Critical threshold in milliseconds
+     */
+    configureIterationStallThresholds(warningMs: number, criticalMs: number): void;
+    get loopState(): RalphTrackerState;
+    /** Last calculated completion confidence */
+    private _lastCompletionConfidence;
+    /** Confidence threshold for triggering completion (0-100) */
+    private static readonly COMPLETION_CONFIDENCE_THRESHOLD;
+    /**
+     * Calculate confidence score for a potential completion signal.
+     *
+     * Scoring weights:
+     * - Promise tag with proper format: +30
+     * - Matches expected phrase: +25
+     * - All todos complete: +20
+     * - EXIT_SIGNAL: true: +15
+     * - Multiple completion indicators (>=2): +10
+     * - Context appropriate (not in prompt/explanation): +10
+     * - Loop was explicitly active: +10
+     *
+     * @param phrase - The detected phrase to evaluate
+     * @param context - Optional surrounding context for the phrase
+     * @returns CompletionConfidence assessment
+     */
+    calculateCompletionConfidence(phrase: string, context?: string): CompletionConfidence;
+    /**
+     * Get all tracked todo items as an array.
+     * @returns Array of todo items (copy, safe to modify)
+     */
+    get todos(): RalphTodoItem[];
+    /**
+     * Process raw terminal data to detect inner loop patterns.
+     *
+     * This is the main entry point for parsing output. Call this with each
+     * chunk of data from the PTY. The tracker will:
+     *
+     * 1. Strip ANSI escape codes
+     * 2. Auto-enable if disabled and Ralph patterns detected
+     * 3. Buffer data and process complete lines
+     * 4. Detect loop status, todos, and completion phrases
+     * 5. Periodically clean up expired todos
+     *
+     * @param data - Raw terminal data (may include ANSI codes)
+     * @fires loopUpdate - When loop state changes
+     * @fires todoUpdate - When todos are detected or updated
+     * @fires completionDetected - When completion phrase found
+     * @fires enabled - When tracker auto-enables
+     */
+    processTerminalData(data: string): void;
+    /**
+     * Process pre-stripped terminal data (ANSI codes already removed).
+     * Use this when the caller has already stripped ANSI to avoid redundant regex work.
+     */
+    processCleanData(cleanData: string): void;
+    /**
+     * Check if data contains patterns that should auto-enable the tracker.
+     *
+     * The tracker auto-enables when any of these patterns are detected:
+     * - `/ralph-loop:ralph-loop` command
+     * - `<promise>PHRASE</promise>` completion tags
+     * - TodoWrite tool usage indicators
+     * - Iteration patterns (`Iteration 5/50`, `[5/50]`)
+     * - Todo checkboxes (`- [ ]`, `- [x]`)
+     * - Todo indicator icons (`☐`, `◐`, `☒`)
+     * - Loop start messages (`Loop started at`)
+     * - All tasks complete announcements
+     * - Task completion signals
+     *
+     * @param data - ANSI-cleaned terminal data
+     * @returns True if any Ralph-related pattern is detected
+     */
+    private shouldAutoEnable;
+    /**
+     * Process a single line of terminal output.
+     * Runs all detection methods in sequence.
+     * @param line - Single line of ANSI-cleaned terminal output
+     */
+    private processLine;
+    /**
+     * Detect "all tasks complete" messages.
+     *
+     * When a valid "all complete" message is detected:
+     * 1. Marks all tracked todos as completed
+     * 2. Emits completion event if a completion phrase is set
+     *
+     * Validation criteria:
+     * - Line must match ALL_COMPLETE_PATTERN
+     * - Line must be reasonably short (<100 chars) to avoid matching commentary
+     * - Must not look like prompt text (no "output:" or `<promise>`)
+     * - Must have at least one tracked todo
+     * - If count is mentioned, should roughly match tracked todo count
+     *
+     * @param line - Single line to check
+     * @fires todoUpdate - If any todos marked complete
+     * @fires completionDetected - If completion phrase was set
+     * @fires loopUpdate - If loop state changes
+     */
+    private detectAllTasksComplete;
+    /**
+     * Detect individual task completion signals
+     * e.g., "Task 8 is done", "marked as completed"
+     *
+     * NOTE: This is intentionally conservative to avoid jitter.
+     * Only marks a todo complete if we can match it by task number.
+     */
+    private detectTaskCompletion;
+    /**
+     * Check for multi-line patterns that might span line boundaries.
+     * Completion phrases can be split across PTY chunks.
+     *
+     * Handles cross-chunk promise tags by:
+     * 1. Checking combined buffer + new data for complete tags
+     * 2. Detecting partial tags at end of chunk and buffering
+     * 3. Clearing buffer when complete tag found or buffer gets stale
+     *
+     * @param data - The full data chunk (may contain multiple lines)
+     */
+    private checkMultiLinePatterns;
+    /**
+     * Detect completion phrases in a line.
+     *
+     * Handles two formats:
+     * 1. Tagged: `<promise>PHRASE</promise>` - Processed via handleCompletionPhrase
+     * 2. Bare: Just `PHRASE` - Only if we already know the expected phrase
+     *
+     * Bare phrase detection avoids false positives by requiring:
+     * - The phrase was previously seen in tagged form
+     * - Line is standalone or ends with the phrase
+     * - Line doesn't look like prompt context
+     *
+     * @param line - Single line to check
+     */
+    private detectCompletionPhrase;
+    /**
+     * Handle a bare completion phrase (without XML tags).
+     *
+     * Only fires completion if:
+     * 1. The phrase was previously seen in tagged form (from prompt)
+     * 2. This is the first bare occurrence (prevents double-firing)
+     *
+     * When triggered:
+     * - Marks all todos as complete
+     * - Emits completionDetected event
+     * - Sets loop to inactive
+     *
+     * @param phrase - The completion phrase text
+     * @fires todoUpdate - If any todos marked complete
+     * @fires completionDetected - When completion triggered
+     * @fires loopUpdate - When loop state changes
+     */
+    private handleBareCompletionPhrase;
+    /**
+     * Handle a detected completion phrase
+     *
+     * Uses occurrence-based detection combined with confidence scoring
+     * to distinguish prompt from actual completion:
+     * - 1st occurrence: Store as expected phrase (likely in prompt)
+     * - 2nd occurrence OR high confidence: Emit completionDetected (actual completion)
+     * - If loop already active: Emit immediately (explicit loop start)
+     */
+    private handleCompletionPhrase;
+    /**
+     * Check if two phrases match with fuzzy tolerance.
+     * Handles variations in:
+     * - Case (COMPLETE vs Complete)
+     * - Whitespace (TASK_DONE vs TASK DONE)
+     * - Separators (TASK_DONE vs TASK-DONE)
+     * - Minor typos with Levenshtein distance (COMPLET vs COMPLETE)
+     *
+     * @param phrase1 - First phrase to compare
+     * @param phrase2 - Second phrase to compare
+     * @param maxDistance - Maximum edit distance for fuzzy match (default: 2)
+     * @returns True if phrases are fuzzy-equal
+     */
+    private isFuzzyPhraseMatch;
+    /**
+     * Validate a completion phrase and emit warnings if it's risky.
+     *
+     * P1-002: Configurable false positive prevention
+     *
+     * Checks for:
+     * - Common/generic phrases (DONE, COMPLETE, etc.)
+     * - Short phrases (< MIN_RECOMMENDED_PHRASE_LENGTH)
+     * - Numeric-only phrases
+     *
+     * @param phrase - The completion phrase to validate
+     * @fires phraseValidationWarning - When a risky phrase is detected
+     */
+    private validateCompletionPhrase;
+    /**
+     * Activate the loop if not already active.
+     *
+     * Sets loop state to active and initializes counters.
+     * No-op if loop is already active.
+     *
+     * @returns True if loop was activated, false if already active
+     * @fires loopUpdate - When loop state changes
+     */
+    private activateLoopIfNeeded;
+    /**
+     * Detect loop start and status indicators.
+     *
+     * Patterns detected:
+     * - Ralph loop start commands (`/ralph-loop:ralph-loop`)
+     * - Loop start messages (`Loop started at`, `Starting Ralph loop`)
+     * - Max iterations setting (`max-iterations 50`)
+     * - Iteration progress (`Iteration 5/50`, `[5/50]`)
+     * - Elapsed time (`Elapsed: 2.5 hours`)
+     * - Cycle count (`cycle #5`, `respawn cycle #3`)
+     * - TodoWrite tool usage
+     *
+     * @param line - Single line to check
+     * @fires loopUpdate - When any loop state changes
+     */
+    private detectLoopStatus;
+    /**
+     * Detect todo items in various formats from Claude Code output.
+     *
+     * Supported formats:
+     * - Format 1: Checkbox markdown (`- [ ] Task`, `- [x] Task`)
+     * - Format 2: Indicator icons (`Todo: ☐ Task`, `Todo: ✓ Task`)
+     * - Format 3: Status in parentheses (`- Task (pending)`)
+     * - Format 4: Native TodoWrite (`☐ Task`, `☒ Task`, `◐ Task`)
+     *
+     * Uses quick pre-check to skip lines that can't contain todos.
+     * Excludes tool invocations and Claude commentary patterns.
+     *
+     * @param line - Single line to check
+     * @fires todoUpdate - When any todos are detected or updated
+     */
+    private detectTodoItems;
+    /**
+     * Convert a todo icon character to its corresponding status.
+     *
+     * Icon mappings:
+     * - Completed: `✓`, `✅`, `☒`, `◉`, `●`
+     * - In Progress: `◐`, `⏳`, `⌛`, `🔄`
+     * - Pending: `☐`, `○`, and anything else (default)
+     *
+     * @param icon - Single character icon
+     * @returns Corresponding RalphTodoStatus
+     */
+    private iconToStatus;
+    /**
+     * Parse priority from todo content.
+     * P1-008: Enhanced keyword-based priority inference.
+     *
+     * Priority levels:
+     * - P0 (Critical): Explicit P0, "critical", "blocker", "urgent", "security", "crash", "broken"
+     * - P1 (High): Explicit P1, "important", "high priority", "bug", "fix", "error", "fail"
+     * - P2 (Medium): Explicit P2, "nice to have", "low priority", "refactor", "cleanup", "improve"
+     *
+     * @param content - Todo content text
+     * @returns Parsed priority level or null
+     */
+    private parsePriority;
+    /**
+     * Add a new todo item or update an existing one.
+     *
+     * Behavior:
+     * - Content is cleaned (ANSI removed, whitespace collapsed)
+     * - Content under 5 chars is skipped
+     * - ID is generated from normalized content (stable hash)
+     * - Priority is parsed from content (P0/P1/P2, Critical, High Priority, etc.)
+     * - Existing item: Updates status and timestamp
+     * - New item: Adds to map, evicts oldest if at MAX_TODOS_PER_SESSION
+     *
+     * @param content - Raw todo content text
+     * @param status - Status to set
+     */
+    private upsertTodo;
+    /**
+     * Normalize todo content for consistent matching.
+     *
+     * Normalization steps:
+     * 1. Collapse multiple whitespace to single space
+     * 2. Remove special characters (keep alphanumeric + basic punctuation)
+     * 3. Trim whitespace
+     * 4. Convert to lowercase
+     *
+     * This prevents duplicate todos from terminal rendering artifacts.
+     *
+     * @param content - Raw todo content
+     * @returns Normalized lowercase string
+     */
+    private normalizeTodoContent;
+    /**
+     * Calculate similarity between two strings.
+     *
+     * P1-007: Uses a hybrid approach combining:
+     * 1. Levenshtein-based similarity for edit-distance tolerance
+     * 2. Bigram (Dice coefficient) for reordering tolerance
+     * Returns the maximum of both methods.
+     *
+     * @param str1 - First string (will be normalized)
+     * @param str2 - Second string (will be normalized)
+     * @returns Similarity score from 0.0 (no similarity) to 1.0 (identical)
+     */
+    private calculateSimilarity;
+    /**
+     * Calculate bigram (Dice coefficient) similarity.
+     * Good for detecting near-duplicates with word reordering.
+     *
+     * @param norm1 - First normalized string
+     * @param norm2 - Second normalized string
+     * @returns Similarity score from 0.0 to 1.0
+     */
+    private calculateBigramSimilarity;
+    /**
+     * Find an existing todo that is similar to the given content.
+     * Returns the most similar todo if similarity >= threshold.
+     *
+     * Deduplication is intentionally conservative:
+     * - Short strings (< 30 chars): require 95% similarity (nearly identical)
+     * - Medium strings (30-60 chars): require 90% similarity
+     * - Longer strings: use default 85% threshold
+     *
+     * This prevents over-aggressive deduplication of brief, numbered items
+     * like "Task 1", "Task 2" while still catching true duplicates.
+     *
+     * @param content - New todo content to check against existing todos
+     * @returns Similar todo item if found, undefined otherwise
+     */
+    private findSimilarTodo;
+    /**
+     * Estimate complexity of a todo based on content keywords.
+     * Used for duration estimation.
+     *
+     * @param content - Todo content text
+     * @returns Complexity category
+     */
+    private estimateComplexity;
+    /**
+     * Get estimated duration for a complexity level (ms).
+     * Based on historical patterns from similar tasks.
+     *
+     * @param complexity - Complexity category
+     * @returns Estimated duration in milliseconds
+     */
+    private getEstimatedDuration;
+    /**
+     * Get average completion time from historical data.
+     * @returns Average time in ms, or null if no data
+     */
+    private getAverageCompletionTime;
+    /**
+     * Record a todo completion for progress tracking.
+     * @param todoId - ID of the completed todo
+     */
+    private recordTodoCompletion;
+    /**
+     * Start tracking a todo for duration estimation.
+     * @param todoId - ID of the todo being started
+     */
+    private startTrackingTodo;
+    /**
+     * Get progress estimation for the todo list.
+     * P1-009: Provides completion percentage, estimated remaining time,
+     * and projected completion timestamp.
+     *
+     * @returns Progress estimation object
+     */
+    getTodoProgress(): RalphTodoProgress;
+    /**
+     * Generate a stable ID from todo content using djb2 hash.
+     *
+     * Uses the djb2 hash algorithm for good distribution across strings.
+     * Content is normalized first to prevent duplicates from terminal artifacts.
+     *
+     * @param content - Todo content text
+     * @returns Stable ID in format `todo-{hash}` (base36 encoded)
+     */
+    /**
+     * Generate a stable ID from todo content using content hashing.
+     *
+     * P1-007: Uses centralized todoContentHash utility for consistency
+     * with deduplication logic.
+     *
+     * @param content - Todo content text
+     * @returns Unique ID string prefixed with "todo-"
+     */
+    private generateTodoId;
+    /**
+     * Find the todo item with the oldest detectedAt timestamp.
+     * Used for LRU eviction when at MAX_TODOS_PER_SESSION limit.
+     * @returns Oldest todo item, or undefined if map is empty
+     */
+    private findOldestTodo;
+    /**
+     * Conditionally run cleanup, throttled to CLEANUP_THROTTLE_MS.
+     * Prevents cleanup from running on every data chunk (performance).
+     */
+    private maybeCleanupExpiredTodos;
+    /**
+     * Remove todo items older than TODO_EXPIRY_MS.
+     * Emits todoUpdate if any items were removed.
+     * @fires todoUpdate - When expired items are removed
+     */
+    private cleanupExpiredTodos;
+    /**
+     * Programmatically start a loop (external API).
+     *
+     * Use when starting a loop from outside terminal detection,
+     * such as from a user action or API call.
+     *
+     * Automatically enables the tracker if not already enabled.
+     *
+     * @param completionPhrase - Optional phrase that signals completion
+     * @param maxIterations - Optional maximum iteration count
+     * @fires enabled - If tracker was disabled
+     * @fires loopUpdate - When loop state changes
+     */
+    startLoop(completionPhrase?: string, maxIterations?: number): void;
+    /**
+     * Update the maximum iteration count (external API).
+     *
+     * @param maxIterations - New max iterations, or null to remove limit
+     * @fires loopUpdate - When loop state changes
+     */
+    setMaxIterations(maxIterations: number | null): void;
+    /**
+     * Configure the tracker from external state (e.g. ralph plugin config).
+     * Only updates fields that are provided, leaving others unchanged.
+     *
+     * @param config - Partial configuration to apply
+     * @fires loopUpdate - When loop state changes
+     */
+    configure(config: {
+        enabled?: boolean;
+        completionPhrase?: string;
+        maxIterations?: number;
+    }): void;
+    /**
+     * Programmatically stop the loop (external API).
+     *
+     * Sets loop to inactive. Does not disable the tracker
+     * or clear todos - use reset() or clear() for that.
+     *
+     * @fires loopUpdate - When loop state changes
+     */
+    stopLoop(): void;
+    /**
+     * Enforce size limit on _taskNumberToContent map.
+     * Removes lowest task numbers (oldest tasks) when limit exceeded.
+     */
+    private enforceTaskMappingLimit;
+    /**
+     * Clear all state and disable the tracker.
+     *
+     * Use when the session is cleared or closed.
+     * Resets everything to initial disabled state.
+     *
+     * @fires loopUpdate - With initial state
+     * @fires todoUpdate - With empty array
+     */
+    clear(): void;
+    /**
+     * Get aggregated statistics about tracked todos.
+     *
+     * @returns Object with counts by status:
+     *   - total: Total number of tracked todos
+     *   - pending: Todos not yet started
+     *   - inProgress: Todos currently in progress
+     *   - completed: Finished todos
+     */
+    getTodoStats(): {
+        total: number;
+        pending: number;
+        inProgress: number;
+        completed: number;
+    };
+    /**
+     * Restore tracker state from persisted data.
+     *
+     * Use after loading state from StateStore. Handles backwards
+     * compatibility by defaulting missing `enabled` flag to false.
+     *
+     * Note: Does not emit events (caller should handle if needed).
+     *
+     * @param loopState - Persisted loop state object
+     * @param todos - Persisted todo items array
+     */
+    restoreState(loopState: RalphTrackerState, todos: RalphTodoItem[]): void;
+    /**
+     * Process a line for RALPH_STATUS block detection.
+     * Buffers lines between ---RALPH_STATUS--- and ---END_RALPH_STATUS---
+     * then parses the complete block.
+     *
+     * @param line - Single line to process (already trimmed)
+     * @fires statusBlockDetected - When a complete block is parsed
+     */
+    private processStatusBlockLine;
+    /**
+     * Parse buffered RALPH_STATUS block lines into structured data.
+     *
+     * P1-004: Enhanced with schema validation and error recovery
+     *
+     * @param lines - Array of lines between block markers
+     * @fires statusBlockDetected - When parsing succeeds
+     */
+    private parseStatusBlock;
+    /**
+     * Handle a parsed RALPH_STATUS block.
+     * Updates circuit breaker, checks exit conditions.
+     *
+     * @param block - Parsed status block
+     * @fires statusBlockDetected - With the block data
+     * @fires circuitBreakerUpdate - If state changes
+     * @fires exitGateMet - If dual-condition exit triggered
+     */
+    private handleStatusBlock;
+    /**
+     * Update circuit breaker state based on iteration results.
+     *
+     * @param hasProgress - Whether this iteration made progress
+     * @param testsStatus - Current test status
+     * @param status - Overall status from RALPH_STATUS
+     * @fires circuitBreakerUpdate - If state changes
+     */
+    private updateCircuitBreaker;
+    /**
+     * Manually reset circuit breaker to CLOSED state.
+     * Use when user acknowledges the issue is resolved.
+     *
+     * @fires circuitBreakerUpdate
+     */
+    resetCircuitBreaker(): void;
+    /**
+     * Get current circuit breaker status.
+     */
+    get circuitBreakerStatus(): CircuitBreakerStatus;
+    /**
+     * Get last parsed RALPH_STATUS block.
+     */
+    get lastStatusBlock(): RalphStatusBlock | null;
+    /**
+     * Get cumulative stats from status blocks.
+     */
+    get cumulativeStats(): {
+        filesModified: number;
+        tasksCompleted: number;
+        completionIndicators: number;
+    };
+    /**
+     * Whether dual-condition exit gate has been met.
+     */
+    get exitGateMet(): boolean;
+    /**
+     * Check line for completion indicators (natural language patterns).
+     * Used for dual-condition exit gate.
+     *
+     * @param line - Line to check
+     */
+    private detectCompletionIndicators;
+    /**
+     * Generate @fix_plan.md content from current todos.
+     * Groups todos by priority and status.
+     *
+     * @returns Markdown content for @fix_plan.md
+     */
+    generateFixPlanMarkdown(): string;
+    /**
+     * Parse @fix_plan.md content and import todos.
+     * Replaces current todos with imported ones.
+     *
+     * @param content - Markdown content from @fix_plan.md
+     * @returns Number of todos imported
+     */
+    importFixPlanMarkdown(content: string): number;
+    /**
+     * Initialize plan tasks from generated plan items.
+     * Called when wizard generates a new plan.
+     */
+    initializePlanTasks(items: Array<{
+        id?: string;
+        content: string;
+        priority?: 'P0' | 'P1' | 'P2' | null;
+        verificationCriteria?: string;
+        testCommand?: string;
+        dependencies?: string[];
+        tddPhase?: TddPhase;
+        pairedWith?: string;
+        complexity?: 'low' | 'medium' | 'high';
+    }>): void;
+    /**
+     * Update a specific plan task's status, attempts, or error.
+     */
+    updatePlanTask(taskId: string, update: {
+        status?: PlanTaskStatus;
+        error?: string;
+        incrementAttempts?: boolean;
+    }): {
+        success: boolean;
+        task?: EnhancedPlanTask;
+        error?: string;
+    };
+    /**
+     * Unblock tasks that were waiting on a completed dependency.
+     */
+    private _unblockDependentTasks;
+    /**
+     * Check if current iteration is a checkpoint and emit review if so.
+     */
+    private _checkForCheckpoint;
+    /**
+     * Generate a checkpoint review summarizing plan progress and stuck tasks.
+     */
+    generateCheckpointReview(): CheckpointReview;
+    /**
+     * Save current plan state to history.
+     */
+    private _savePlanToHistory;
+    /**
+     * Get plan version history.
+     */
+    getPlanHistory(): Array<{
+        version: number;
+        timestamp: number;
+        summary: string;
+        stats: {
+            total: number;
+            completed: number;
+            failed: number;
+        };
+    }>;
+    /**
+     * Rollback to a previous plan version.
+     */
+    rollbackToVersion(version: number): {
+        success: boolean;
+        plan?: EnhancedPlanTask[];
+        error?: string;
+    };
+    /**
+     * Add a new task to the plan (for runtime adaptation).
+     */
+    addPlanTask(task: {
+        content: string;
+        priority?: 'P0' | 'P1' | 'P2';
+        verificationCriteria?: string;
+        dependencies?: string[];
+        insertAfter?: string;
+    }): {
+        task: EnhancedPlanTask;
+    };
+    /**
+     * Get all plan tasks.
+     */
+    getPlanTasks(): EnhancedPlanTask[];
+    /**
+     * Get current plan version.
+     */
+    get planVersion(): number;
+    /**
+     * Check if checkpoint review is due for current iteration.
+     */
+    isCheckpointDue(): boolean;
+    /**
+     * Clean up all resources and release memory.
+     *
+     * Call this when the session is being destroyed to prevent memory leaks.
+     * Stops file watchers, clears all timers, data, and removes event listeners.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=ralph-tracker.d.ts.map