surrogate-protocol-mcp 2.0.0

package/dist/utils/reconcile.js

@@ -0,0 +1,262 @@
+// surrogate-tools/src/utils/reconcile.ts
+// Reconciler: Ensures state consistency after crashes, hangs, or partial completions (WS1-4)
+// P2-2: Enhanced with comprehensive reconcileState that properly completes/fails surrogates
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { loadState, updateState, PROJECT_ROOT, reconcileState, } from './state.js';
+// ═══════════════════════════════════════════════════════════════════════════
+// PROCESS CHECKING
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Check if a process with given PID is still running.
+ */
+function isProcessRunning(pid) {
+    try {
+        // Signal 0 doesn't kill, just checks if process exists
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the .surrogate-result.json marker from a worktree.
+ */
+function readLocalResultMarker(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 {
+        console.error(`[Reconcile] Failed to parse marker at ${markerPath}`);
+        return null;
+    }
+}
+/**
+ * Check if a worktree exists and is valid.
+ */
+function isWorktreeValid(worktreePath) {
+    if (!fs.existsSync(worktreePath)) {
+        return false;
+    }
+    // Check if it's a valid git worktree
+    try {
+        execSync('git rev-parse --git-dir', {
+            cwd: worktreePath,
+            stdio: 'pipe',
+            encoding: 'utf8',
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read the agent status file from .surrogate/status/<id>.json
+ */
+function readAgentStatusFile(id) {
+    const statusPath = path.resolve(PROJECT_ROOT, '.surrogate', 'status', `${id}.json`);
+    if (!fs.existsSync(statusPath)) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(statusPath, 'utf8');
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// P2-2: ENHANCED RECONCILIATION (USES STATE.TS reconcileState)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * P2-2: Enhanced reconcile that properly completes/fails surrogates.
+ * This version:
+ * - Moves completed/failed surrogates to recent_completed
+ * - Cleans up orphaned status files
+ * - Cleans up orphaned locks
+ * - Uses typed failures with evidence
+ *
+ * @param dryRun - If true, only report what would be done
+ * @returns Comprehensive reconcile result
+ */
+export function reconcileAllEnhanced(dryRun = false) {
+    return reconcileState(dryRun);
+}
+// ═══════════════════════════════════════════════════════════════════════════
+// LEGACY RECONCILIATION (for backward compatibility)
+// ═══════════════════════════════════════════════════════════════════════════
+/**
+ * Reconcile a single surrogate's state based on actual system state.
+ * @deprecated Use reconcileAllEnhanced instead
+ */
+function reconcileSurrogateLegacy(surrogate) {
+    const { id, status, worktree } = surrogate;
+    const agentPid = surrogate.agent_pid;
+    // Skip already terminal states
+    if (status === 'COMPLETE' || status === 'FAILED') {
+        return null;
+    }
+    // Check worktree validity
+    const worktreeValid = isWorktreeValid(worktree.path);
+    if (!worktreeValid) {
+        return {
+            surrogate_id: id,
+            previous_status: status,
+            new_status: 'FAILED',
+            reason: `Worktree missing or invalid: ${worktree.path}`,
+        };
+    }
+    // Read result marker
+    const marker = readLocalResultMarker(worktree.path);
+    // Read agent status file (written by agent-runner)
+    const agentStatus = readAgentStatusFile(id);
+    // Check if process is still running
+    const processRunning = agentPid ? isProcessRunning(agentPid) : false;
+    // Decision tree for reconciliation
+    if (marker) {
+        // Marker exists - agent completed
+        if (marker.success) {
+            // Success marker - should be REVIEWING
+            if (status !== 'REVIEWING') {
+                return {
+                    surrogate_id: id,
+                    previous_status: status,
+                    new_status: 'REVIEWING',
+                    reason: `Agent completed successfully (marker found): ${marker.message || 'success'}`,
+                };
+            }
+        }
+        else {
+            // Failure marker
+            return {
+                surrogate_id: id,
+                previous_status: status,
+                new_status: 'FAILED',
+                reason: `Agent reported failure: ${marker.message || 'unknown error'}`,
+            };
+        }
+    }
+    else if (!processRunning && (status === 'CODING' || status === 'INITIALIZING')) {
+        // No marker and process not running - crashed
+        const agentStatusStr = agentStatus ? agentStatus.status : 'unknown';
+        return {
+            surrogate_id: id,
+            previous_status: status,
+            new_status: 'FAILED',
+            reason: `Agent process not running (PID: ${agentPid || 'unknown'}), no result marker. Last known status: ${agentStatusStr}`,
+        };
+    }
+    else if (agentStatus && agentStatus.status === 'TIMEOUT') {
+        return {
+            surrogate_id: id,
+            previous_status: status,
+            new_status: 'TIMEOUT',
+            reason: 'Agent timed out (per status file)',
+        };
+    }
+    else if (agentStatus && agentStatus.status === 'CONFIG_ERROR') {
+        return {
+            surrogate_id: id,
+            previous_status: status,
+            new_status: 'CONFIG_ERROR',
+            reason: 'Agent configuration error (per status file)',
+        };
+    }
+    // No reconciliation needed
+    return null;
+}
+/**
+ * Reconcile all active surrogates (legacy version - updates status in place).
+ * @deprecated Use reconcileAllEnhanced for full lifecycle management
+ *
+ * This version is kept for backward compatibility. It only updates
+ * the status field without moving surrogates to recent_completed.
+ */
+export function reconcileAll() {
+    const actions = [];
+    const errors = [];
+    const state = loadState();
+    for (const surrogate of state.active_surrogates) {
+        try {
+            const action = reconcileSurrogateLegacy(surrogate);
+            if (action) {
+                actions.push(action);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`Failed to reconcile ${surrogate.id}: ${message}`);
+        }
+    }
+    // Apply actions to state (legacy: just updates status in place)
+    if (actions.length > 0) {
+        updateState((state) => {
+            for (const action of actions) {
+                const surrogate = state.active_surrogates.find((s) => s.id === action.surrogate_id);
+                if (surrogate) {
+                    surrogate.status = action.new_status;
+                    if (surrogate.error_details === undefined) {
+                        surrogate.error_details = action.reason;
+                    }
+                }
+            }
+        });
+    }
+    return {
+        reconciled: actions.length,
+        actions,
+        errors,
+    };
+}
+/**
+ * Check for drift without making changes.
+ * Returns list of surrogates that would be reconciled.
+ */
+export function driftCheck() {
+    const drifted = [];
+    const errors = [];
+    const state = loadState();
+    for (const surrogate of state.active_surrogates) {
+        try {
+            const action = reconcileSurrogateLegacy(surrogate);
+            if (action) {
+                drifted.push(action);
+            }
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            errors.push(`Failed to check ${surrogate.id}: ${message}`);
+        }
+    }
+    return { drifted, errors };
+}
+/**
+ * Force-fail a specific surrogate and clean up its resources.
+ * @deprecated Use failSurrogateState with TypedFailure instead
+ */
+export function forceFailSurrogate(id, reason) {
+    try {
+        updateState((state) => {
+            const surrogate = state.active_surrogates.find((s) => s.id === id);
+            if (surrogate) {
+                surrogate.status = 'FAILED';
+                surrogate.error_details = `Force-failed: ${reason}`;
+            }
+        });
+        return { success: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { success: false, error: message };
+    }
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/utils/reconcile.js.map

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

package/dist/utils/state.d.ts

@@ -0,0 +1,241 @@
+export declare const PROJECT_ROOT: string;
+export type SurrogateStatus = 'INITIALIZING' | 'CODING' | 'TESTING' | 'REVIEWING' | 'MERGE_CONFLICT' | 'SPAWN_FAILED' | 'CONFIG_ERROR' | 'TIMEOUT' | 'COMPLETE' | 'FAILED';
+/**
+ * Error type enum - fail_surrogate MUST use one of these types.
+ * Free-form "reason-only" failures are not allowed.
+ */
+export type FailureErrorType = 'AUTH' | 'TIMEOUT' | 'TOOLING_MISSING' | 'GATE_FAILED' | 'POLICY_VIOLATION' | 'MERGE_CONFLICT' | 'DEPENDENCY_ERROR' | 'SYNTAX_ERROR' | 'RUNTIME_ERROR' | 'TASK_IMPOSSIBLE' | 'EXTERNAL_BLOCKER';
+/**
+ * Evidence required for fail_surrogate.
+ * At least one of exit_code+stderr OR log_path must be provided.
+ */
+export interface FailureEvidence {
+    exit_code?: number;
+    stderr_tail?: string;
+    stdout_tail?: string;
+    log_path?: string;
+    command?: string;
+    gate_name?: string;
+    conflicting_files?: string[];
+}
+/**
+ * Typed failure request - replaces free-form "reason" string.
+ */
+export interface TypedFailure {
+    error_type: FailureErrorType;
+    message: string;
+    evidence: FailureEvidence;
+}
+/**
+ * Validate that evidence is sufficient for the error type.
+ */
+export declare function validateFailureEvidence(failure: TypedFailure): {
+    valid: boolean;
+    error?: string;
+};
+export interface Surrogate {
+    id: string;
+    role: string;
+    task_description: string;
+    status: SurrogateStatus;
+    worktree: {
+        path: string;
+        branch: string;
+        created: string;
+    };
+    file_locks: {
+        exclusive: string[];
+        read_only: string[];
+    };
+    dependencies: {
+        surrogate_id: string;
+        imports: string[];
+    }[];
+    test_gate: {
+        test_written: boolean;
+        test_failing: boolean;
+        test_path?: string;
+    };
+    started: string;
+    last_heartbeat: string;
+    error_details?: string;
+}
+export interface CompletedSurrogate extends Surrogate {
+    completed_at: string;
+    pr_number?: number;
+    pr_url?: string;
+    artifacts: {
+        files_created: {
+            path: string;
+            exports?: string[];
+        }[];
+        files_modified: {
+            path: string;
+            changes: string;
+        }[];
+        tests_added: string[];
+    };
+    report_path: string;
+}
+export interface FlightRecorder {
+    meta: {
+        project: string;
+        initialized: string;
+        last_updated: string;
+        context_version: number;
+        archive_pointer?: string;
+    };
+    mission: {
+        objective: string | null;
+        decomposition: {
+            task_id: string;
+            description: string;
+            assigned_to: string | null;
+            status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETE' | 'FAILED';
+        }[];
+    };
+    active_surrogates: Surrogate[];
+    recent_completed: CompletedSurrogate[];
+    file_locks: Record<string, string>;
+    constraints: {
+        forbidden_paths: string[];
+        protected_paths: string[];
+        required_patterns: string[];
+    };
+    config: {
+        heartbeat_ttl_minutes: number;
+        scoped_tests: boolean;
+        cleanup_on_complete: boolean;
+    };
+    statistics: {
+        total_spawned: number;
+        total_completed: number;
+        total_failed: number;
+        total_merged: number;
+    };
+}
+export declare function ensureDirectories(): void;
+export declare function loadState(): FlightRecorder;
+export declare function saveState(state: FlightRecorder): void;
+/**
+ * Thread-safe state update with advisory lock (WS1-3).
+ * Prevents race conditions when multiple processes update state concurrently.
+ */
+export declare function updateState(updater: (state: FlightRecorder) => void): FlightRecorder;
+export declare function addSurrogate(id: string, role: string, task: string, worktreePath: string, branch: string, fileLocks: string[]): FlightRecorder;
+export declare function updateSurrogateStatus(id: string, status: Surrogate['status']): FlightRecorder;
+export declare function completeSurrogateState(id: string, artifacts: CompletedSurrogate['artifacts'], prUrl?: string): FlightRecorder;
+/**
+ * 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 declare function failSurrogateState(id: string, failure: TypedFailure): FlightRecorder;
+/**
+ * Legacy fail_surrogate for backward compatibility.
+ * Deprecated: Use failSurrogateState with TypedFailure instead.
+ */
+export declare function failSurrogateStateLegacy(id: string, reason: string): FlightRecorder;
+/**
+ * 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 declare function canonicalLockPath(filePath: string): string;
+/**
+ * Normalize an array of file paths to canonical lock format.
+ */
+export declare function canonicalLockPaths(files: string[]): string[];
+export declare function checkLockConflict(files: string[]): {
+    hasConflict: boolean;
+    conflicts: {
+        file: string;
+        owner: string;
+    }[];
+};
+export declare function getLockedFiles(): Record<string, string>;
+/**
+ * Clean up status file when surrogate completes or fails
+ */
+export declare function cleanupAgentStatusFile(surrogateId: string): void;
+export interface StatusSummary {
+    mission: string | null;
+    context_version: number;
+    active_count: number;
+    active_surrogates: {
+        id: string;
+        role: string;
+        status: string;
+        task: string;
+        locks: string[];
+    }[];
+    locked_files: string[];
+    recent_completed_count: number;
+    statistics: FlightRecorder['statistics'];
+}
+export declare function getStatusSummary(): StatusSummary & {
+    stale_surrogates: string[];
+};
+/**
+ * Emergency force release locks for a surrogate (WS3-3).
+ * WARNING: This is a destructive operation - does not properly clean up state.
+ */
+export declare function forceReleaseLocks(surrogateId: string): {
+    released: string[];
+    errors: string[];
+};
+export declare function checkProtectedFiles(files: string[]): {
+    hasProtected: boolean;
+    protected: string[];
+};
+/**
+ * Result of checking a single surrogate's actual state.
+ */
+export interface SurrogateReconcileCheck {
+    id: string;
+    status_in_yaml: string;
+    actual_status: 'RUNNING' | 'COMPLETED' | 'FAILED' | 'ORPHANED' | 'ZOMBIE' | 'STALE';
+    has_result_marker: boolean;
+    has_status_file: boolean;
+    process_alive: boolean;
+    worktree_exists: boolean;
+    issue?: string;
+    action_taken?: string;
+    marker_data?: {
+        success: boolean;
+        error_type?: string;
+        error_message?: string;
+        duration_ms?: number;
+    };
+}
+/**
+ * Result of the full reconcile operation.
+ */
+export interface ReconcileResult {
+    timestamp: string;
+    checks: SurrogateReconcileCheck[];
+    orphaned_status_files: string[];
+    orphaned_worktrees: string[];
+    orphaned_locks: {
+        file: string;
+        owner: string;
+    }[];
+    actions_taken: string[];
+    state_was_corrected: boolean;
+    summary: string;
+}
+/**
+ * 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 declare function reconcileState(dryRun?: boolean): ReconcileResult;
+//# sourceMappingURL=state.d.ts.map

package/dist/utils/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/utils/state.ts"],"names":[],"mappings":"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"}