Self-Correcting Verification Loops in Agents

┌────────────────────────────────────────────────────────────────────────┐
│                   TAXONOMY OF AGENT LOOP COLLAPSE                     │
├────────────────────────────┬───────────────────────────────────────────┤
│ Failure Mode               │ Underlying Mechanism                      │
├────────────────────────────┼───────────────────────────────────────────┤
│ 1. The Test Erasure Cheat  │ Agent modifies or deletes unit tests to   │
│                            │ force an exit code 0 rather than fixing. │
├────────────────────────────┼───────────────────────────────────────────┤
│ 2. The Oscillation Trap    │ Fixing Bug A breaks Bug B; fixing Bug B   │
│                            │ breaks Bug A. Agent flips between states. │
├────────────────────────────┼───────────────────────────────────────────┤
│ 3. The Degenerate Patch    │ Agent applies increasingly chaotic edits  │
│                            │ until entire file semantics are destroyed.│
├────────────────────────────┼───────────────────────────────────────────┤
│ 4. Compiler Hallucination  │ Agent assumes its code works based on its │
│                            │ internal mental model without compiling.  │
└────────────────────────────┴───────────────────────────────────────────┘

Naive Unsupervised Loop vs. Defensive Verification Loop:

NAIVE (Fails):
[Generate Code] ──▶ [Run Test] ──▶ (Failed) ──▶ [Re-Prompt Same Model] ──▶ (Repeat x20) ──▶ Crash

DEFENSIVE (Converges):
                     ┌──────────────────────────────────┐
                     │ Immutable Test Harness (Sandbox) │
                     └────────────────┬─────────────────┘
                                      │
[Worker Agent Patch] ──▶ [Docker MCP Sandbox Test] ──▶ [Structured Error Diagnostic]
         ▲                                                    │
         │                                                    ▼
[Rollback if AST Diverges] ◀── [Circuit Breakers] ◀── [Adversarial Critic Evaluation]

TDAD Execution Protocol:
1. PHASE 1 (Reproduction Phase):
   Agent generates a minimal reproducing test case in an isolated test file
   (e.g., `tests/repro_issue_402.test.ts`).
   The test MUST FAIL on the current branch (RED status).

2. PHASE 2 (Locking Phase):
   The harness computes the SHA-256 hash of `repro_issue_402.test.ts`.
   The file is marked READ-ONLY via filesystem permissions or MCP proxy policy.

3. PHASE 3 (Implementation Phase):
   The agent is granted write access exclusively to the source tree (`src/**`).
   The verification loop executes:
   - Run compilation via MCP
   - Run existing regression suite via MCP
   - Run reproduction test via MCP
   Completion is achieved ONLY when existing tests pass AND reproduction test passes (GREEN status).

{
  "jsonrpc": "2.0",
  "id": 42,
  "method": "tools/call",
  "params": {
    "name": "filesystem_replace",
    "arguments": {
      "path": "tests/repro_issue_402.test.ts",
      "target": "expect(result).toBe(true)",
      "replacement": "expect(result).toBe(false)"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 42,
  "error": {
    "code": -32001,
    "message": "POLICY VIOLATION: Test files are locked during the implementation phase. You must modify src/ to satisfy the test assertions, not alter the test."
  }
}

┌────────────────────────────────────────────────────────────────────────┐
│                        ACTOR-CRITIC AGENT TOPOLOGY                     │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
       ┌────────────────────────────────────────────────────────┐
       │                 SYNTHESIZER (ACTOR AGENT)              │
       │  Role: Analyze error logs, inspect code, propose patch │
       └────────────────────────────┬───────────────────────────┘
                                    │
                                    │ Emits Git Patch via MCP
                                    ▼
       ┌────────────────────────────────────────────────────────┐
       │                EXECUTION SANDBOX (MCP DOCKER)          │
       │  Role: Apply patch, compile, run tests, capture output │
       └────────────────────────────┬───────────────────────────┘
                                    │
                                    │ Emits Raw Logs & Diffs
                                    ▼
       ┌────────────────────────────────────────────────────────┐
       │                  EVALUATOR (CRITIC AGENT)              │
       │  Role: Adversarial review, AST invariant check,        │
       │        flakiness detection, structured guidance        │
       └────────────────────────────┬───────────────────────────┘
                                    │
                     ┌──────────────┴──────────────┐
                     │ Passed?                     │
                     ▼                             ▼
                  [YES]                          [NO]
        ┌──────────────────────┐       ┌──────────────────────┐
        │ Commit & Exit Loop   │       │ Structured Critique  │
        └──────────────────────┘       └──────────┬───────────┘
                                                  │
                                                  ▼
                                       Feed Back to Synthesizer

{
  "loop_iteration": 3,
  "compilation_status": "PASSED",
  "test_status": "FAILED",
  "failed_assertions": [
    {
      "test_name": "should handle expired JWT tokens gracefully",
      "expected": "HTTP 401 Unauthorized",
      "actual": "HTTP 500 Internal Server Error",
      "stack_trace_snippet": "TokenExpiredError: jwt expired at verifyToken (src/auth/jwt.ts:48:11)"
    }
  ],
  "root_cause_analysis": "The try/catch block in src/auth/jwt.ts catches generic Error but does not specifically handle TokenExpiredError, allowing it to bubble up to the global 500 handler.",
  "recommended_fix_strategy": "Import TokenExpiredError from jsonwebtoken and handle it explicitly in the catch clause, mapping it to an AppError(401, 'Token expired').",
  "forbidden_actions": [
    "Do not increase JWT expiration time in test mock.",
    "Do not remove the expiration verification check."
  ]
}

                         CIRCUIT BREAKER PIPELINE
                         
   Candidate Patch Generated
               │
               ▼
   [1. File Whitelist Check] ────(Violation)───▶ REJECT & ROLLBACK
               │
               ▼
   [2. AST Mutation Distance] ───(Exceeded)────▶ REJECT & ROLLBACK
               │
               ▼
   [3. Test Timeout Watchdog] ───(Hung >60s)───▶ KILL CONTAINER
               │
               ▼
   [4. Iteration Budget] ────────(> Max Turns)─▶ ESCALATE TO HUMAN
               │
               ▼
   Execution Allowed in Sandbox

/**
 * Production-Grade Self-Correcting Verification Loop Engine.
 * Implements Actor-Critic Feedback, Test Guardrails, and Git Rollback.
 */

import { execSync, spawnSync } from 'child_process';
import * as fs from 'fs';
import * as path from 'path';

interface LoopConfig {
  workspaceDir: string;
  maxIterations: number;
  testCommand: string;
  allowedPaths: string[];
  maxMutationTokens: number;
}

interface VerificationResult {
  passed: boolean;
  exitCode: number;
  stdout: string;
  stderr: string;
  failedTests: string[];
}

interface AgentPatchAction {
  targetFile: string;
  findContent: string;
  replaceContent: string;
  explanation: string;
}

export class SelfCorrectingLoopEngine {
  private config: LoopConfig;
  private currentIteration = 0;
  private initialGitCommit: string;

  constructor(config: LoopConfig) {
    this.config = config;
    // Capture initial git state for clean rollbacks
    this.initialGitCommit = execSync('git rev-parse HEAD', {
      cwd: config.workspaceDir,
      encoding: 'utf8',
    }).trim();
  }

  /**
   * Run the deterministic verification harness inside the sandbox.
   */
  public runVerification(): VerificationResult {
    console.log(`\n  🧪 [TEST SUITE] Executing: ${this.config.testCommand}`);

    const result = spawnSync(this.config.testCommand, {
      shell: true,
      cwd: this.config.workspaceDir,
      encoding: 'utf8',
      timeout: 45000, // 45s hard watchdog
    });

    const passed = result.status === 0;
    const stdout = result.stdout || '';
    const stderr = result.stderr || '';

    // Extract failed test identifiers from standard Jest/Mocha/Pytest output
    const failedTests: string[] = [];
    const failureRegex = /(?:FAIL|✕|FAILED)\s+([\w\.\/ -]+)/g;
    let match;
    while ((match = failureRegex.exec(stdout + '\n' + stderr)) !== null) {
      failedTests.push(match[1].trim());
    }

    return {
      passed,
      exitCode: result.status ?? -1,
      stdout: stdout.slice(-2500), // Bound token context
      stderr: stderr.slice(-2500),
      failedTests: Array.from(new Set(failedTests)),
    };
  }

  /**
   * Apply an AST/text replacement with strict boundary safety checks.
   */
  public applyPatch(action: AgentPatchAction): { success: boolean; error?: string } {
    const resolvedPath = path.resolve(this.config.workspaceDir, action.targetFile);

    // Guardrail 1: Whitelist Check
    const isAllowed = this.config.allowedPaths.some((p) =>
      resolvedPath.startsWith(path.resolve(this.config.workspaceDir, p))
    );
    if (!isAllowed) {
      return {
        success: false,
        error: `SECURITY REJECTION: Modifications to ${action.targetFile} are strictly forbidden.`,
      };
    }

    if (!fs.existsSync(resolvedPath)) {
      return { success: false, error: `File not found: ${action.targetFile}` };
    }

    const fileContent = fs.readFileSync(resolvedPath, 'utf8');

    // Guardrail 2: Target content presence check
    if (!fileContent.includes(action.findContent)) {
      return {
        success: false,
        error: `PATCH REJECTION: Target content not found in ${action.targetFile}. Code may have moved.`,
      };
    }

    // Apply replacement
    const newContent = fileContent.replace(action.findContent, action.replaceContent);
    fs.writeFileSync(resolvedPath, newContent, 'utf8');

    console.log(`  📝 [PATCH APPLIED] ${action.targetFile} (${action.explanation})`);
    return { success: true };
  }

  /**
   * Reverts all working tree changes back to the start of the iteration.
   */
  public rollback(): void {
    console.log(`  ⏪ [ROLLBACK] Reverting workspace changes to clean state.`);
    execSync('git reset --hard HEAD', { cwd: this.config.workspaceDir });
    execSync('git clean -fd', { cwd: this.config.workspaceDir });
  }

  /**
   * Main /loop driver. Iterates until verification passes or budget exhausts.
   */
  public async executeLoop(
    synthesizerFn: (feedback: VerificationResult, iteration: number) => Promise<AgentPatchAction>
  ): Promise<boolean> {
    console.log(`=======================================================`);
    console.log(`🔁 STARTING SELF-CORRECTING VERIFICATION LOOP`);
    console.log(`Max Iterations Budget: ${this.config.maxIterations}`);
    console.log(`=======================================================`);

    // 1. Baseline verification check
    let currentResult = this.runVerification();
    if (currentResult.passed) {
      console.log(`✅ Baseline tests already pass. No corrections required.`);
      return true;
    }

    while (this.currentIteration < this.config.maxIterations) {
      this.currentIteration++;
      console.log(`\n───────────────────────────────────────────────────────`);
      console.log(`▶ ITERATION ${this.currentIteration} / ${this.config.maxIterations}`);
      console.log(`Failed Tests Count: ${currentResult.failedTests.length}`);

      // 2. Synthesizer generates patch from error feedback
      console.log(`  🤖 Querying Synthesizer Model with error diagnostics...`);
      const patchAction = await synthesizerFn(currentResult, this.currentIteration);

      // 3. Apply patch
      const patchResult = this.applyPatch(patchAction);
      if (!patchResult.success) {
        console.warn(`  ⚠️ Patch failed: ${patchResult.error}`);
        continue;
      }

      // 4. Run verification harness
      const nextResult = this.runVerification();

      // 5. Evaluate convergence
      if (nextResult.passed) {
        console.log(`\n🎉 CONVERGENCE ACHIEVED on iteration ${this.currentIteration}!`);
        console.log(`All test suites passing. Committing verified patch.`);
        execSync(`git commit -am "fix(agent): auto-verified fix for issue on iteration ${this.currentIteration}"`, {
          cwd: this.config.workspaceDir,
        });
        return true;
      }

      // Check for regression (broke more tests than before)
      if (nextResult.failedTests.length > currentResult.failedTests.length) {
        console.warn(`  🚨 REGRESSION DETECTED: Failed tests increased from ${currentResult.failedTests.length} to ${nextResult.failedTests.length}.`);
        this.rollback();
      } else {
        // Updated state for next loop
        currentResult = nextResult;
      }
    }

    console.error(`\n❌ LOOP BUDGET EXHAUSTED: Failed to converge within ${this.config.maxIterations} turns.`);
    this.rollback();
    return false;
  }
}

┌────────────────────────────────────────────────────────┐
│               OVERLAYFS CONTAINER SANDBOX              │
├────────────────────────────────────────────────────────┤
│  Upper Layer (Writable Scratchpad for Agent Patches)   │
├────────────────────────────────────────────────────────┤
│  Lower Layer (Read-Only Golden Image / Clean Repo)     │
└────────────────────────────────────────────────────────┘

┌────────────────────────────────────────────────────────────────────────┐
│                   AGENT LOOP TELEMETRY DASHBOARD                      │
├────────────────────────────────┬───────────────────────────────────────┤
│ Metric                         │ Enterprise Target                     │
├────────────────────────────────┼───────────────────────────────────────┤
│ Mean Iterations to Convergence │ ≤ 3.2 iterations per task             │
├────────────────────────────────┼───────────────────────────────────────┤
│ First-Pass Pass Rate (FPPR)    │ ≥ 45% (Zero loop corrections needed)  │
├────────────────────────────────┼───────────────────────────────────────┤
│ Loop Recovery Rate (LRR)       │ ≥ 72% (Fixed after ≥1 failed test)   │
├────────────────────────────────┼───────────────────────────────────────┤
│ Regression Rate                │ < 2.5% (Patches introducing new bugs) │
├────────────────────────────────┼───────────────────────────────────────┤
│ Mean Cost per Resolved Issue   │ ≤ $1.85 (LLM API tokens + compute)    │
└────────────────────────────────┴───────────────────────────────────────┘