surrogate-protocol-mcp 2.0.0

package/dist/utils/state.js

@@ -0,0 +1,865 @@
+// surrogate-tools/src/utils/state.ts
+// Safe YAML state management - LLMs NEVER touch this file directly
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'yaml';
+// Resolve project root from current working directory
+export const PROJECT_ROOT = process.cwd();
+const SURROGATE_DIR = '.surrogate';
+const FLIGHT_RECORDER = path.join(SURROGATE_DIR, 'flight_recorder.yaml');
+const ARCHIVE_DIR = path.join(SURROGATE_DIR, 'archive');
+const STATUS_DIR = path.join(SURROGATE_DIR, 'status'); // Sharded agent status files
+/**
+ * Validate that evidence is sufficient for the error type.
+ */
+export function validateFailureEvidence(failure) {
+    const { error_type, evidence } = failure;
+    // Evidence must have at least one of: (exit_code + stderr) OR log_path
+    const hasProcessEvidence = evidence.exit_code !== undefined || evidence.stderr_tail !== undefined;
+    const hasLogEvidence = evidence.log_path !== undefined;
+    if (!hasProcessEvidence && !hasLogEvidence) {
+        return {
+            valid: false,
+            error: 'Evidence required: provide exit_code/stderr_tail OR log_path',
+        };
+    }
+    // Type-specific validation
+    switch (error_type) {
+        case 'GATE_FAILED':
+            if (!evidence.gate_name) {
+                return { valid: false, error: 'GATE_FAILED requires evidence.gate_name' };
+            }
+            break;
+        case 'MERGE_CONFLICT':
+            if (!evidence.conflicting_files || evidence.conflicting_files.length === 0) {
+                return { valid: false, error: 'MERGE_CONFLICT requires evidence.conflicting_files' };
+            }
+            break;
+        case 'TOOLING_MISSING':
+            if (!evidence.command) {
+                return { valid: false, error: 'TOOLING_MISSING requires evidence.command' };
+            }
+            break;
+    }
+    return { valid: true };
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// STATE OPERATIONS
+// ═══════════════════════════════════════════════════════════════════════════
+const LOCK_FILE = path.join(SURROGATE_DIR, 'flight_recorder.lock');
+const LOCK_TIMEOUT_MS = 10000; // 10 seconds max wait
+const LOCK_RETRY_MS = 50; // Retry every 50ms
+const LOCK_STALE_MS = 60000; // Consider lock stale after 60 seconds
+/**
+ * Advisory lock for YAML state file (WS1-3).
+ * Prevents race conditions during concurrent read-modify-write operations.
+ */
+function acquireLock() {
+    ensureDirectories();
+    const startTime = Date.now();
+    while (Date.now() - startTime < LOCK_TIMEOUT_MS) {
+        try {
+            // Check for stale lock
+            if (fs.existsSync(LOCK_FILE)) {
+                const lockStat = fs.statSync(LOCK_FILE);
+                const lockAge = Date.now() - lockStat.mtimeMs;
+                if (lockAge > LOCK_STALE_MS) {
+                    console.error(`[State] Removing stale lock (age: ${Math.round(lockAge / 1000)}s)`);
+                    fs.unlinkSync(LOCK_FILE);
+                }
+            }
+            // Try to create lock file exclusively
+            const fd = fs.openSync(LOCK_FILE, 'wx');
+            fs.writeSync(fd, JSON.stringify({ pid: process.pid, time: new Date().toISOString() }));
+            fs.closeSync(fd);
+            return {
+                acquired: true,
+                release: () => {
+                    try {
+                        if (fs.existsSync(LOCK_FILE)) {
+                            fs.unlinkSync(LOCK_FILE);
+                        }
+                    }
+                    catch {
+                        // Ignore release errors
+                    }
+                },
+            };
+        }
+        catch (error) {
+            if (error.code === 'EEXIST') {
+                // Lock exists, wait and retry
+                const waitTime = LOCK_RETRY_MS + Math.random() * LOCK_RETRY_MS;
+                Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitTime);
+            }
+            else {
+                throw error;
+            }
+        }
+    }
+    console.error('[State] Failed to acquire lock within timeout');
+    return { acquired: false, release: () => { } };
+}
+export function ensureDirectories() {
+    const dirs = [SURROGATE_DIR, ARCHIVE_DIR, STATUS_DIR, path.join(SURROGATE_DIR, 'worktrees')];
+    dirs.forEach(dir => {
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+    });
+}
+export function loadState() {
+    ensureDirectories();
+    if (!fs.existsSync(FLIGHT_RECORDER)) {
+        return createInitialState();
+    }
+    try {
+        const content = fs.readFileSync(FLIGHT_RECORDER, 'utf8');
+        return yaml.parse(content);
+    }
+    catch (error) {
+        // WS1-3: Don't silently reset - backup corrupt file
+        const backupPath = `${FLIGHT_RECORDER}.corrupt.${Date.now()}`;
+        console.error(`[State] YAML parse failed, backing up to ${backupPath}`);
+        try {
+            fs.copyFileSync(FLIGHT_RECORDER, backupPath);
+        }
+        catch {
+            // Ignore backup errors
+        }
+        console.error('[State] Creating fresh state after corruption');
+        return createInitialState();
+    }
+}
+export function saveState(state) {
+    ensureDirectories();
+    // Update metadata
+    state.meta.last_updated = new Date().toISOString();
+    state.meta.context_version++;
+    // Auto-archive if too many completed surrogates
+    archiveIfNeeded(state);
+    // Validate before saving
+    validateState(state);
+    // Atomic write (write to temp, then rename)
+    const tempPath = `${FLIGHT_RECORDER}.tmp`;
+    fs.writeFileSync(tempPath, yaml.stringify(state, { lineWidth: 0 }));
+    fs.renameSync(tempPath, FLIGHT_RECORDER);
+}
+/**
+ * Thread-safe state update with advisory lock (WS1-3).
+ * Prevents race conditions when multiple processes update state concurrently.
+ */
+export function updateState(updater) {
+    const lock = acquireLock();
+    if (!lock.acquired) {
+        throw new Error('Failed to acquire state lock - another process may be updating');
+    }
+    try {
+        const state = loadState();
+        updater(state);
+        saveState(state);
+        return state;
+    }
+    finally {
+        lock.release();
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// SURROGATE OPERATIONS
+// ═══════════════════════════════════════════════════════════════════════════
+export function addSurrogate(id, role, task, worktreePath, branch, fileLocks) {
+    // Normalize file locks to canonical format (WS1-2)
+    const normalizedLocks = canonicalLockPaths(fileLocks);
+    return updateState(state => {
+        // Add surrogate
+        const surrogate = {
+            id,
+            role,
+            task_description: task,
+            status: 'INITIALIZING',
+            worktree: {
+                path: worktreePath,
+                branch,
+                created: new Date().toISOString(),
+            },
+            file_locks: {
+                exclusive: normalizedLocks, // Store normalized paths
+                read_only: [],
+            },
+            dependencies: [],
+            test_gate: {
+                test_written: false,
+                test_failing: false,
+            },
+            started: new Date().toISOString(),
+            last_heartbeat: new Date().toISOString(),
+        };
+        state.active_surrogates.push(surrogate);
+        // Add file locks (using normalized paths)
+        normalizedLocks.forEach(file => {
+            state.file_locks[file] = id;
+        });
+        // Update statistics
+        state.statistics.total_spawned++;
+    });
+}
+export function updateSurrogateStatus(id, status) {
+    return updateState(state => {
+        const surrogate = state.active_surrogates.find(s => s.id === id);
+        if (surrogate) {
+            surrogate.status = status;
+            surrogate.last_heartbeat = new Date().toISOString();
+        }
+    });
+}
+export function completeSurrogateState(id, artifacts, prUrl) {
+    return updateState(state => {
+        const surrogateIndex = state.active_surrogates.findIndex(s => s.id === id);
+        if (surrogateIndex === -1) {
+            throw new Error(`Surrogate ${id} not found`);
+        }
+        const surrogate = state.active_surrogates[surrogateIndex];
+        // Create completed record
+        const completed = {
+            ...surrogate,
+            status: 'COMPLETE',
+            completed_at: new Date().toISOString(),
+            pr_url: prUrl,
+            artifacts,
+            report_path: `.surrogate/reports/${id}-report.yaml`,
+        };
+        // Move to recent_completed
+        state.recent_completed.push(completed);
+        // Remove from active
+        state.active_surrogates.splice(surrogateIndex, 1);
+        // Release file locks
+        surrogate.file_locks.exclusive.forEach(file => {
+            delete state.file_locks[file];
+        });
+        // Update statistics
+        state.statistics.total_completed++;
+        // Cleanup agent status file (sharded state)
+        cleanupAgentStatusFile(id);
+    });
+}
+/**
+ * P2-1: Typed fail_surrogate with evidence requirement.
+ * Rejects failures without proper evidence.
+ *
+ * @param id - Surrogate ID
+ * @param failure - Typed failure with error_type, message, and evidence
+ * @throws Error if evidence is insufficient
+ */
+export function failSurrogateState(id, failure) {
+    // Validate evidence first
+    const validation = validateFailureEvidence(failure);
+    if (!validation.valid) {
+        throw new Error(`EVIDENCE_REQUIRED: ${validation.error}. Cannot fail surrogate without proper evidence.`);
+    }
+    return updateState(state => {
+        const surrogateIndex = state.active_surrogates.findIndex(s => s.id === id);
+        if (surrogateIndex === -1) {
+            throw new Error(`Surrogate ${id} not found`);
+        }
+        const surrogate = state.active_surrogates[surrogateIndex];
+        // Map error_type to appropriate status
+        let status = 'FAILED';
+        if (failure.error_type === 'TIMEOUT')
+            status = 'TIMEOUT';
+        else if (failure.error_type === 'MERGE_CONFLICT')
+            status = 'MERGE_CONFLICT';
+        else if (failure.error_type === 'AUTH' || failure.error_type === 'TOOLING_MISSING')
+            status = 'CONFIG_ERROR';
+        // Create failed record
+        const failed = {
+            ...surrogate,
+            status,
+            completed_at: new Date().toISOString(),
+            artifacts: { files_created: [], files_modified: [], tests_added: [] },
+            report_path: `.surrogate/reports/${id}-failed.yaml`,
+            error_details: failure.message,
+        };
+        // Write structured failure report (P2-1: includes all evidence)
+        const reportPath = path.join(SURROGATE_DIR, 'reports', `${id}-failed.yaml`);
+        fs.mkdirSync(path.dirname(reportPath), { recursive: true });
+        fs.writeFileSync(reportPath, yaml.stringify({
+            id,
+            error_type: failure.error_type,
+            message: failure.message,
+            evidence: failure.evidence,
+            failed_at: new Date().toISOString(),
+            status,
+        }));
+        // Move to recent_completed
+        state.recent_completed.push(failed);
+        // Remove from active
+        state.active_surrogates.splice(surrogateIndex, 1);
+        // Release file locks
+        surrogate.file_locks.exclusive.forEach(file => {
+            delete state.file_locks[file];
+        });
+        // Update statistics
+        state.statistics.total_failed++;
+        // Cleanup agent status file (sharded state)
+        cleanupAgentStatusFile(id);
+    });
+}
+/**
+ * Legacy fail_surrogate for backward compatibility.
+ * Deprecated: Use failSurrogateState with TypedFailure instead.
+ */
+export function failSurrogateStateLegacy(id, reason) {
+    // Convert legacy reason to typed failure with minimal evidence
+    const failure = {
+        error_type: 'TASK_IMPOSSIBLE',
+        message: reason,
+        evidence: {
+            log_path: `.surrogate/logs/${id}.log`,
+        },
+    };
+    return failSurrogateState(id, failure);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// LOCK OPERATIONS
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Canonical lock path normalization (WS1-2).
+ * Ensures consistent path format regardless of input style:
+ * - Converts backslashes to forward slashes (Windows compatibility)
+ * - Removes leading ./ or .\
+ * - Removes trailing slashes
+ * - Normalizes to lowercase on Windows
+ */
+export function canonicalLockPath(filePath) {
+    let normalized = filePath
+        .replace(/\\/g, '/') // Backslash -> forward slash
+        .replace(/^\.\//, '') // Remove leading ./
+        .replace(/^\.\\/, '') // Remove leading .\
+        .replace(/\/+$/, '') // Remove trailing slashes
+        .replace(/\/+/g, '/'); // Collapse multiple slashes
+    // On Windows, normalize to lowercase for case-insensitive matching
+    if (process.platform === 'win32') {
+        normalized = normalized.toLowerCase();
+    }
+    return normalized;
+}
+/**
+ * Normalize an array of file paths to canonical lock format.
+ */
+export function canonicalLockPaths(files) {
+    return files.map(canonicalLockPath);
+}
+export function checkLockConflict(files) {
+    const state = loadState();
+    const conflicts = [];
+    // Normalize incoming files for comparison
+    const normalizedFiles = canonicalLockPaths(files);
+    normalizedFiles.forEach((file, index) => {
+        if (state.file_locks[file]) {
+            conflicts.push({ file: files[index], owner: state.file_locks[file] });
+        }
+    });
+    return { hasConflict: conflicts.length > 0, conflicts };
+}
+export function getLockedFiles() {
+    return loadState().file_locks;
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// ARCHIVING
+// ═══════════════════════════════════════════════════════════════════════════
+function archiveIfNeeded(state) {
+    const MAX_RECENT = 5;
+    const MAX_TOKENS_ESTIMATE = 2000;
+    // Archive if too many recent completed
+    while (state.recent_completed.length > MAX_RECENT) {
+        const oldest = state.recent_completed.shift();
+        if (oldest) {
+            appendToArchive(oldest);
+        }
+    }
+    // Rough token estimate (chars / 4)
+    const stateSize = yaml.stringify(state).length / 4;
+    if (stateSize > MAX_TOKENS_ESTIMATE && state.recent_completed.length > 1) {
+        const oldest = state.recent_completed.shift();
+        if (oldest) {
+            appendToArchive(oldest);
+        }
+    }
+}
+function appendToArchive(surrogate) {
+    const date = new Date().toISOString().split('T')[0];
+    const archivePath = path.join(ARCHIVE_DIR, `history-${date}.yaml`);
+    let archive = [];
+    if (fs.existsSync(archivePath)) {
+        archive = yaml.parse(fs.readFileSync(archivePath, 'utf8')) || [];
+    }
+    archive.push(surrogate);
+    fs.writeFileSync(archivePath, yaml.stringify(archive));
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// VALIDATION
+// ═══════════════════════════════════════════════════════════════════════════
+function validateState(state) {
+    // Check for duplicate surrogate IDs
+    const ids = state.active_surrogates.map(s => s.id);
+    const duplicates = ids.filter((id, index) => ids.indexOf(id) !== index);
+    if (duplicates.length > 0) {
+        throw new Error(`Duplicate surrogate IDs detected: ${duplicates.join(', ')}`);
+    }
+    // Check for orphaned locks
+    const activeIds = new Set(state.active_surrogates.map(s => s.id));
+    Object.entries(state.file_locks).forEach(([file, owner]) => {
+        if (!activeIds.has(owner)) {
+            console.warn(`Warning: Orphaned lock on ${file} by non-existent surrogate ${owner}`);
+            delete state.file_locks[file];
+        }
+    });
+}
+function createInitialState() {
+    const state = {
+        meta: {
+            project: path.basename(process.cwd()),
+            initialized: new Date().toISOString(),
+            last_updated: new Date().toISOString(),
+            context_version: 1,
+        },
+        mission: {
+            objective: null,
+            decomposition: [],
+        },
+        active_surrogates: [],
+        recent_completed: [],
+        file_locks: {},
+        constraints: {
+            forbidden_paths: ['node_modules/*', '.env*', '.git/*', '.surrogate/flight_recorder.yaml'],
+            protected_paths: ['package.json', 'package-lock.json', 'yarn.lock', 'pnpm-lock.yaml'],
+            required_patterns: [],
+        },
+        config: {
+            heartbeat_ttl_minutes: 5, // Auto-kill after 5 min silence
+            scoped_tests: true, // Use --findRelatedTests by default
+            cleanup_on_complete: true, // Clean worktree after successful merge
+        },
+        statistics: {
+            total_spawned: 0,
+            total_completed: 0,
+            total_failed: 0,
+            total_merged: 0,
+        },
+    };
+    saveState(state);
+    return state;
+}
+/**
+ * Read all agent status files from .surrogate/status/
+ * Each agent writes only to its own file (no race condition)
+ */
+function readAgentStatusFiles() {
+    const statusMap = new Map();
+    ensureDirectories();
+    if (!fs.existsSync(STATUS_DIR)) {
+        return statusMap;
+    }
+    try {
+        const files = fs.readdirSync(STATUS_DIR).filter(f => f.endsWith('.json'));
+        for (const file of files) {
+            try {
+                const content = fs.readFileSync(path.join(STATUS_DIR, file), 'utf8');
+                const status = JSON.parse(content);
+                statusMap.set(status.surrogate_id, status);
+            }
+            catch {
+                // Skip corrupted files
+                console.error(`[State] Failed to read status file: ${file}`);
+            }
+        }
+    }
+    catch {
+        // Directory read error - return empty
+    }
+    return statusMap;
+}
+/**
+ * Clean up status file when surrogate completes or fails
+ */
+export function cleanupAgentStatusFile(surrogateId) {
+    const statusFile = path.join(STATUS_DIR, `${surrogateId}.json`);
+    try {
+        if (fs.existsSync(statusFile)) {
+            fs.unlinkSync(statusFile);
+        }
+    }
+    catch {
+        console.error(`[State] Failed to cleanup status file for ${surrogateId}`);
+    }
+}
+export function getStatusSummary() {
+    const state = loadState();
+    const agentStatuses = readAgentStatusFiles(); // Real-time from agents
+    const now = Date.now();
+    const ttlMs = (state.config?.heartbeat_ttl_minutes || 5) * 60 * 1000;
+    // Merge YAML state with real-time agent status
+    const mergedSurrogates = state.active_surrogates.map(s => {
+        const agentStatus = agentStatuses.get(s.id);
+        // If agent has written a status file, use its real-time data
+        if (agentStatus) {
+            return {
+                ...s,
+                status: agentStatus.status,
+                last_heartbeat: agentStatus.last_heartbeat,
+            };
+        }
+        return s;
+    });
+    // Detect stale surrogates (no heartbeat within TTL)
+    // Uses MERGED data (real-time from agent files)
+    const staleSurrogates = mergedSurrogates
+        .filter(s => {
+        const lastHeartbeat = new Date(s.last_heartbeat).getTime();
+        return (now - lastHeartbeat) > ttlMs;
+    })
+        .map(s => s.id);
+    return {
+        mission: state.mission.objective,
+        context_version: state.meta.context_version,
+        active_count: mergedSurrogates.length,
+        active_surrogates: mergedSurrogates.map(s => ({
+            id: s.id,
+            role: s.role,
+            status: s.status,
+            task: s.task_description,
+            locks: s.file_locks.exclusive,
+        })),
+        locked_files: Object.keys(state.file_locks),
+        recent_completed_count: state.recent_completed.length,
+        statistics: state.statistics,
+        stale_surrogates: staleSurrogates, // Surrogates that need cleanup
+    };
+}
+/**
+ * Emergency force release locks for a surrogate (WS3-3).
+ * WARNING: This is a destructive operation - does not properly clean up state.
+ */
+export function forceReleaseLocks(surrogateId) {
+    const released = [];
+    const errors = [];
+    try {
+        updateState(state => {
+            const surrogate = state.active_surrogates.find(s => s.id === surrogateId);
+            if (!surrogate) {
+                errors.push(`Surrogate '${surrogateId}' not found in active surrogates`);
+                return;
+            }
+            // Release all file locks owned by this surrogate
+            for (const [file, owner] of Object.entries(state.file_locks)) {
+                if (owner === surrogateId) {
+                    delete state.file_locks[file];
+                    released.push(file);
+                }
+            }
+            // Clear the surrogate's lock list
+            surrogate.file_locks.exclusive = [];
+            surrogate.file_locks.read_only = [];
+        });
+    }
+    catch (error) {
+        errors.push(error instanceof Error ? error.message : String(error));
+    }
+    return { released, errors };
+}
+// Check if file is protected (requires explicit lock acknowledgment)
+export function checkProtectedFiles(files) {
+    const state = loadState();
+    const protectedPaths = state.constraints?.protected_paths || [];
+    const protectedFiles = files.filter(file => protectedPaths.some(p => file === p || file.endsWith(`/${p}`)));
+    return { hasProtected: protectedFiles.length > 0, protected: protectedFiles };
+}
+/**
+ * Check if a process is alive by PID.
+ */
+function isProcessAlive(pid) {
+    try {
+        // On Unix, signal 0 checks if process exists without killing it
+        // On Windows, this throws if process doesn't exist
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read result marker from a worktree.
+ */
+function readResultMarkerFromWorktree(worktreePath) {
+    const markerPath = path.join(worktreePath, '.surrogate-result.json');
+    if (!fs.existsSync(markerPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(markerPath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Scan for orphaned worktrees (exist but not in active_surrogates).
+ */
+function findOrphanedWorktrees(state) {
+    const worktreesDir = path.join(SURROGATE_DIR, 'worktrees');
+    if (!fs.existsSync(worktreesDir)) {
+        return [];
+    }
+    const activeIds = new Set(state.active_surrogates.map(s => s.id));
+    const orphaned = [];
+    try {
+        const entries = fs.readdirSync(worktreesDir, { withFileTypes: true });
+        for (const entry of entries) {
+            if (entry.isDirectory() && !activeIds.has(entry.name)) {
+                orphaned.push(entry.name);
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return orphaned;
+}
+/**
+ * Scan for orphaned status files (exist but surrogate not in active list).
+ */
+function findOrphanedStatusFiles(state) {
+    if (!fs.existsSync(STATUS_DIR)) {
+        return [];
+    }
+    const activeIds = new Set(state.active_surrogates.map(s => s.id));
+    const orphaned = [];
+    try {
+        const files = fs.readdirSync(STATUS_DIR).filter(f => f.endsWith('.json'));
+        for (const file of files) {
+            const id = file.replace('.json', '');
+            if (!activeIds.has(id)) {
+                orphaned.push(id);
+            }
+        }
+    }
+    catch {
+        // Ignore read errors
+    }
+    return orphaned;
+}
+/**
+ * Reconcile a single surrogate's state against reality.
+ */
+function reconcileSurrogate(surrogate, dryRun) {
+    const check = {
+        id: surrogate.id,
+        status_in_yaml: surrogate.status,
+        actual_status: 'RUNNING',
+        has_result_marker: false,
+        has_status_file: false,
+        process_alive: false,
+        worktree_exists: false,
+    };
+    // Check if worktree exists
+    const worktreePath = surrogate.worktree.path;
+    check.worktree_exists = fs.existsSync(worktreePath);
+    // Check for result marker in worktree
+    if (check.worktree_exists) {
+        const marker = readResultMarkerFromWorktree(worktreePath);
+        if (marker) {
+            check.has_result_marker = true;
+            check.marker_data = {
+                success: marker.success,
+                error_type: marker.error_type,
+                error_message: marker.error_message,
+                duration_ms: marker.duration_ms,
+            };
+        }
+    }
+    // Check for status file
+    const statusFile = path.join(STATUS_DIR, `${surrogate.id}.json`);
+    check.has_status_file = fs.existsSync(statusFile);
+    // Check if process is alive (if we have a PID)
+    const pid = surrogate.agent_pid;
+    if (pid) {
+        check.process_alive = isProcessAlive(pid);
+    }
+    // Determine actual status
+    if (check.has_result_marker) {
+        // Agent wrote a result marker - it's done
+        check.actual_status = check.marker_data?.success ? 'COMPLETED' : 'FAILED';
+        check.issue = `Result marker exists (success=${check.marker_data?.success}) but surrogate still in active list`;
+    }
+    else if (!check.worktree_exists) {
+        // Worktree is gone but surrogate is still active
+        check.actual_status = 'ORPHANED';
+        check.issue = 'Worktree does not exist but surrogate is in active list';
+    }
+    else if (pid && !check.process_alive) {
+        // Process died without writing a marker
+        check.actual_status = 'ZOMBIE';
+        check.issue = `Process ${pid} is not running and no result marker was written`;
+    }
+    else {
+        // Check for stale heartbeat
+        const ttlMs = 5 * 60 * 1000; // 5 minutes
+        const lastHeartbeat = new Date(surrogate.last_heartbeat).getTime();
+        const now = Date.now();
+        if ((now - lastHeartbeat) > ttlMs) {
+            check.actual_status = 'STALE';
+            check.issue = `No heartbeat for ${Math.round((now - lastHeartbeat) / 60000)} minutes`;
+        }
+        else {
+            check.actual_status = 'RUNNING';
+        }
+    }
+    return check;
+}
+/**
+ * P2-2: Main reconcile function.
+ * Scans all surrogates and corrects state based on evidence from markers and reports.
+ *
+ * @param dryRun - If true, don't modify state, just report what would be done
+ * @returns ReconcileResult with all findings and actions taken
+ */
+export function reconcileState(dryRun = false) {
+    const result = {
+        timestamp: new Date().toISOString(),
+        checks: [],
+        orphaned_status_files: [],
+        orphaned_worktrees: [],
+        orphaned_locks: [],
+        actions_taken: [],
+        state_was_corrected: false,
+        summary: '',
+    };
+    const state = loadState();
+    // 1. Check each active surrogate
+    for (const surrogate of state.active_surrogates) {
+        const check = reconcileSurrogate(surrogate, dryRun);
+        result.checks.push(check);
+    }
+    // 2. Find orphaned status files
+    result.orphaned_status_files = findOrphanedStatusFiles(state);
+    // 3. Find orphaned worktrees
+    result.orphaned_worktrees = findOrphanedWorktrees(state);
+    // 4. Find orphaned locks (locks without active surrogate)
+    const activeIds = new Set(state.active_surrogates.map(s => s.id));
+    for (const [file, owner] of Object.entries(state.file_locks)) {
+        if (!activeIds.has(owner)) {
+            result.orphaned_locks.push({ file, owner });
+        }
+    }
+    // 5. Take corrective actions (unless dry run)
+    if (!dryRun) {
+        // Process surrogates that need correction
+        for (const check of result.checks) {
+            if (check.actual_status === 'COMPLETED' && check.marker_data?.success) {
+                // Agent completed successfully - mark as complete
+                try {
+                    completeSurrogateState(check.id, {
+                        files_created: [],
+                        files_modified: [],
+                        tests_added: [],
+                    });
+                    check.action_taken = 'Marked as COMPLETE based on result marker';
+                    result.actions_taken.push(`Completed ${check.id}`);
+                    result.state_was_corrected = true;
+                }
+                catch (error) {
+                    check.action_taken = `Failed to complete: ${error}`;
+                }
+            }
+            else if (check.actual_status === 'FAILED' && check.has_result_marker) {
+                // Agent failed - mark as failed with evidence from marker
+                try {
+                    const errorType = mapMarkerErrorTypeToFailureType(check.marker_data?.error_type);
+                    failSurrogateState(check.id, {
+                        error_type: errorType,
+                        message: check.marker_data?.error_message || 'Agent failed (from reconcile)',
+                        evidence: {
+                            log_path: `.surrogate/logs/${check.id}.log`,
+                        },
+                    });
+                    check.action_taken = 'Marked as FAILED based on result marker';
+                    result.actions_taken.push(`Failed ${check.id} (${errorType})`);
+                    result.state_was_corrected = true;
+                }
+                catch (error) {
+                    check.action_taken = `Failed to mark as failed: ${error}`;
+                }
+            }
+            else if (check.actual_status === 'ZOMBIE' || check.actual_status === 'ORPHANED') {
+                // Process died or worktree gone - mark as failed
+                try {
+                    failSurrogateState(check.id, {
+                        error_type: 'RUNTIME_ERROR',
+                        message: check.issue || `Surrogate ${check.actual_status.toLowerCase()} - detected by reconcile`,
+                        evidence: {
+                            log_path: `.surrogate/logs/${check.id}.log`,
+                        },
+                    });
+                    check.action_taken = `Marked as FAILED (${check.actual_status})`;
+                    result.actions_taken.push(`Failed ${check.id} (${check.actual_status})`);
+                    result.state_was_corrected = true;
+                }
+                catch (error) {
+                    check.action_taken = `Failed to mark as failed: ${error}`;
+                }
+            }
+        }
+        // Clean up orphaned status files
+        for (const id of result.orphaned_status_files) {
+            try {
+                const statusFile = path.join(STATUS_DIR, `${id}.json`);
+                fs.unlinkSync(statusFile);
+                result.actions_taken.push(`Deleted orphaned status file: ${id}`);
+                result.state_was_corrected = true;
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+        // Clean up orphaned locks
+        if (result.orphaned_locks.length > 0) {
+            updateState(s => {
+                for (const lock of result.orphaned_locks) {
+                    delete s.file_locks[lock.file];
+                }
+            });
+            result.actions_taken.push(`Released ${result.orphaned_locks.length} orphaned locks`);
+            result.state_was_corrected = true;
+        }
+    }
+    // Generate summary
+    const issueCount = result.checks.filter(c => c.actual_status !== 'RUNNING').length;
+    const orphanCount = result.orphaned_status_files.length +
+        result.orphaned_worktrees.length +
+        result.orphaned_locks.length;
+    if (issueCount === 0 && orphanCount === 0) {
+        result.summary = 'State is consistent - no issues found';
+    }
+    else if (dryRun) {
+        result.summary = `Found ${issueCount} surrogate issues, ${orphanCount} orphaned resources (dry run - no changes made)`;
+    }
+    else {
+        result.summary = `Corrected ${result.actions_taken.length} issues`;
+    }
+    return result;
+}
+/**
+ * Map marker error types to TypedFailure error types.
+ */
+function mapMarkerErrorTypeToFailureType(markerType) {
+    switch (markerType) {
+        case 'TIMEOUT': return 'TIMEOUT';
+        case 'CONFIG_ERROR': return 'AUTH';
+        case 'SPAWN_FAILED': return 'TOOLING_MISSING';
+        case 'EXECUTION_ERROR': return 'RUNTIME_ERROR';
+        default: return 'RUNTIME_ERROR';
+    }
+}
+//# sourceMappingURL=state.js.map