GitHub Actions AI Cost Control: Agent-Triggered Workflow Fan-Out, Parallel Job Log Accumulation, Matrix Build Context Explosion, and CI Feedback Loop Amplification

GitHub Actions is the CI/CD layer most AI coding agents treat as a validation oracle. When an AI agent — GitHub Copilot Workspace, an autonomous coding agent built on the Claude or GPT-4o API, or a home-grown agent that commits code and checks the result — uses Actions as a feedback signal, the pattern is always the same: the agent makes a code change, triggers a workflow run (explicitly via workflow_dispatch or implicitly via a push), waits for the result, reads the logs, generates a fix, and repeats. This trigger–run–read–fix loop is structurally sound when it converges in one or two iterations. It produces runaway cost when it does not.

The cost drivers in GitHub Actions AI loops are both compute (GitHub-hosted runner minutes) and context (LLM input tokens consumed when the agent reads workflow logs to generate the next fix). These two cost surfaces are independent but compound each other: a loop that triggers 10 workflow runs wastes 10× the expected runner-minutes, and if each failed run's logs are injected into the agent's context window, those logs contribute 10× the expected token cost for the read step. The total cost of a non-converging agent–CI loop is the product of both multipliers, not their sum.

GitHub Actions also has a fan-out architecture that multiplies cost beyond what the triggering agent expects. A push to a repository with a standard workflow file triggers one workflow — but that workflow may contain 12 jobs running in parallel, a matrix strategy multiplying those 12 jobs across 4 OS and Node.js version combinations (48 runner instances total), and a completion trigger that fires a downstream deployment workflow. An agent expecting to pay for one validation run is actually paying for 48 parallel jobs plus a second workflow, and reading logs from all of them when any job fails.

The root architecture that makes this expensive is GitHub Actions' design as a general-purpose CI system: it is optimized for thoroughness and parallelism, not for economical feedback in rapid agent iteration loops. Four structural cost patterns emerge at the intersection of agent automation and GitHub Actions' execution model. Each has a circuit breaker guard that imposes budget discipline without degrading the validation signal.

Pattern 1: Agent-Triggered Workflow Fan-Out

When an AI agent pushes a commit or calls the GitHub API to trigger a workflow_dispatch event, it initiates a workflow run. The agent's model of this event is typically one-to-one: one trigger, one run, one result to read. The actual execution graph is usually more complex. A push event in a typical production repository triggers not one workflow but every workflow file in .github/workflows/ that matches the push event's branch and path filters — commonly a ci.yml for tests, a lint.yml for static analysis, a build.yml for artifact creation, and a security.yml for dependency audits. These four workflows run concurrently and independently, each consuming separate runner-minutes.

The fan-out compounds further through workflow chaining. A build.yml workflow that succeeds may trigger a deploy-staging.yml via a workflow_run event. A deploy-staging.yml that succeeds may trigger a smoke-test.yml. An agent that pushes one commit to fix a type error can inadvertently kick off a three-stage deployment pipeline consuming 45 minutes of runner time, invoking cloud provider APIs for staging deployments, and generating log output across 8 distinct workflow runs — all before the agent has read a single result.

The worst case is recursive fan-out from auto-fix workflows. Some teams configure an autofix.yml workflow that runs ESLint with --fix and commits the result if any fixes were applied. An AI agent that pushes code with lint errors triggers: (1) ci.yml which fails on lint, (2) autofix.yml which commits lint fixes and pushes, (3) a second ci.yml run from the autofix commit, (4) a second autofix.yml run from the second push — creating a push–autofix–push cascade that consumes 4× the expected runner-minutes before either the CI passes or the cascade limit trips.

interface WorkflowTriggerEvent {
  sha: string;
  triggeredAt: Date;
  workflowsStarted: string[];  // workflow file names
  chainDepth: number;          // 0 = agent push, 1 = workflow_run trigger, etc.
}

interface FanOutState {
  iterationCount: number;
  totalWorkflowsTriggered: number;
  totalRunnerMinutesEstimated: number;
  triggerHistory: WorkflowTriggerEvent[];
  autoFixPushCount: number;
}

class GHAFanOutGuard {
  private state: FanOutState = {
    iterationCount: 0,
    totalWorkflowsTriggered: 0,
    totalRunnerMinutesEstimated: 0,
    triggerHistory: [],
    autoFixPushCount: 0,
  };

  constructor(
    private readonly maxIterations: number = 8,
    private readonly maxWorkflowsPerSession: number = 40,
    private readonly maxRunnerMinutes: number = 120,
    private readonly maxChainDepth: number = 2,
    private readonly avgMinutesPerWorkflow: number = 8,
  ) {}

  onAgentCommit(sha: string, expectedWorkflowCount: number): void {
    this.state.iterationCount++;

    if (this.state.iterationCount > this.maxIterations) {
      throw new Error(
        `GHAFanOutGuard: iteration ceiling ${this.maxIterations} reached. ` +
        `Agent has pushed ${this.state.iterationCount} commits in this session ` +
        `triggering ${this.state.totalWorkflowsTriggered} workflow runs. ` +
        `Halt and review the recurring failure before continuing.`,
      );
    }

    this.state.totalWorkflowsTriggered += expectedWorkflowCount;
    this.state.totalRunnerMinutesEstimated +=
      expectedWorkflowCount * this.avgMinutesPerWorkflow;

    if (this.state.totalRunnerMinutesEstimated > this.maxRunnerMinutes) {
      throw new Error(
        `GHAFanOutGuard: estimated runner-minutes ${this.state.totalRunnerMinutesEstimated} ` +
        `exceeds ceiling ${this.maxRunnerMinutes} after ${this.state.iterationCount} iterations. ` +
        `Estimated cost: $${(this.state.totalRunnerMinutesEstimated * 0.008).toFixed(2)} ` +
        `(ubuntu-latest). Consider switching to a branch with deploy workflows disabled ` +
        `for agent iteration commits.`,
      );
    }

    if (this.state.totalWorkflowsTriggered > this.maxWorkflowsPerSession) {
      throw new Error(
        `GHAFanOutGuard: ${this.state.totalWorkflowsTriggered} total workflows triggered ` +
        `this session exceeds ceiling ${this.maxWorkflowsPerSession}. ` +
        `Agent commit loop is fanning out beyond the expected validation scope.`,
      );
    }

    this.state.triggerHistory.push({
      sha, triggeredAt: new Date(),
      workflowsStarted: [], chainDepth: 0,
    });
  }

  onAutoFixPush(sha: string): void {
    this.state.autoFixPushCount++;
    if (this.state.autoFixPushCount >= 2) {
      throw new Error(
        `GHAFanOutGuard: autofix push cascade detected (${this.state.autoFixPushCount} autofix commits). ` +
        `The autofix workflow is re-triggering itself. ` +
        `Disable the autofix.yml workflow on the agent's working branch ` +
        `or set AUTOFIX_SKIP=true in the commit message.`,
      );
    }
  }

  onWorkflowChainEvent(parentSha: string, chainDepth: number, workflowName: string): void {
    if (chainDepth > this.maxChainDepth) {
      throw new Error(
        `GHAFanOutGuard: workflow chain depth ${chainDepth} from commit ${parentSha.slice(0,8)} ` +
        `exceeds ceiling ${this.maxChainDepth}. ` +
        `${workflowName} was triggered by a workflow_run event. ` +
        `Agent commits should not propagate into deployment chains during iteration.`,
      );
    }
  }

  get summary(): FanOutState {
    return { ...this.state };
  }
}

GHAFanOutGuard tracks the cumulative workflow and runner-minute cost across all commits the agent makes in a session. Call onAgentCommit(sha, expectedWorkflowCount) before each push, using the GitHub API's GET /repos/{owner}/{repo}/actions/workflows to count workflows with matching event triggers. Call onAutoFixPush when the agent detects a push it did not initiate (via GET /repos/{owner}/{repo}/commits comparing the latest SHA to the agent's last known SHA). The maxChainDepth ceiling is the most important guard for preventing deployment fan-out from agent iteration commits.

Pattern 2: Parallel Job Log Context Accumulation

When a GitHub Actions workflow run fails, an AI agent needs to read the failure details to generate a fix. The GitHub API provides workflow logs through two endpoints: GET /repos/{owner}/{repo}/actions/runs/{run_id}/logs returns a zip archive of all job logs (can be 2–50MB), and GET /repos/{owner}/{repo}/actions/jobs/{job_id}/logs returns one job's plain-text log. Most agents use the per-job endpoint, iterating through all failed jobs in the run. The accumulation problem is structural: a workflow with 8 parallel jobs may have only 2 failing jobs, but the agent must retrieve and parse all 8 job logs to determine which 2 failed — because the GitHub API's GET /repos/{owner}/{repo}/actions/runs/{run_id}/jobs endpoint returns job status (success/failure) without log content.

Each GitHub Actions job log is a time-stamped line stream of every command the runner executed: the job setup output (25–60 lines of runner initialization), each run: step's stdout and stderr (10 lines to 8,000+ lines for complex build steps), and the job summary (5–15 lines). A job running a TypeScript compilation step with errors produces: the tsc command invocation line, every file with an error listed with its path and error text (1–4 lines per error, 30–80 errors typical for a significant type mismatch), the total error count line, and the exit code. A job running a 500-test Jest suite produces: 500+ lines of test names and results, the summary table (10 lines), the failed test output (20–100 lines per failing test), and coverage output if enabled (30–80 lines). A single job log in a TypeScript project with failing tests routinely reaches 3,000–8,000 lines.

The parallel job accumulation pattern emerges when the agent reads all job logs to understand a run failure. A workflow with jobs: lint (passes, 120 lines), type-check (fails, 850 lines of TypeScript errors), test (fails, 4,200 lines with 8 failing tests), build (fails, 1,100 lines of webpack output), e2e (skipped due to test failure, 45 lines), security (passes, 200 lines) — presents the agent with 6,515 lines of log content across 6 parallel jobs. At ~4 tokens per log line (job logs include timestamps, ANSI codes, and prefixes), this is 26,000 tokens of log content injected into the agent's context for a single workflow run. Across 5 iteration cycles, the agent receives 130,000 tokens of log content, on top of whatever code context it maintains.

interface JobLogRead {
  jobId: number;
  jobName: string;
  conclusion: 'success' | 'failure' | 'skipped' | 'cancelled' | null;
  rawLines: number;
  truncatedLines: number;
  tokensEstimated: number;
}

interface JobLogState {
  runReadsTotal: number;
  cumulativeLogTokens: number;
  currentRunJobReads: JobLogRead[];
  failingJobsRead: number;
  passingJobsRead: number;
}

class GHAJobLogGuard {
  private state: JobLogState = {
    runReadsTotal: 0,
    cumulativeLogTokens: 0,
    currentRunJobReads: [],
    failingJobsRead: 0,
    passingJobsRead: 0,
  };

  constructor(
    private readonly maxLogLinesPerJob: number = 200,
    private readonly maxLogLinesPerRun: number = 800,
    private readonly maxCumulativeLogTokens: number = 80_000,
    private readonly tokensPerLine: number = 4,
    private readonly readPassingJobs: boolean = false,
  ) {}

  processJobLog(
    jobId: number,
    jobName: string,
    conclusion: JobLogRead['conclusion'],
    rawLog: string,
  ): string {
    const rawLines = rawLog.split('\n').length;

    if (!this.readPassingJobs && conclusion === 'success') {
      this.state.passingJobsRead++;
      return '';
    }

    const lines = rawLog.split('\n');
    const truncated = lines.length > this.maxLogLinesPerJob
      ? [
          ...lines.slice(0, 30),
          `... [${lines.length - this.maxLogLinesPerJob} lines truncated] ...`,
          ...lines.slice(-Math.max(0, this.maxLogLinesPerJob - 30)),
        ].join('\n')
      : rawLog;

    const truncatedLines = truncated.split('\n').length;
    const tokensEstimated = Math.round(truncatedLines * this.tokensPerLine);

    this.state.cumulativeLogTokens += tokensEstimated;
    if (conclusion === 'failure') this.state.failingJobsRead++;

    this.state.currentRunJobReads.push({
      jobId, jobName, conclusion, rawLines, truncatedLines, tokensEstimated,
    });

    if (this.state.cumulativeLogTokens > this.maxCumulativeLogTokens) {
      throw new Error(
        `GHAJobLogGuard: cumulative log tokens ${this.state.cumulativeLogTokens.toLocaleString()} ` +
        `exceeds ceiling ${this.maxCumulativeLogTokens.toLocaleString()} across ${this.state.runReadsTotal} runs. ` +
        `Log injection is dominating agent context. ` +
        `Switch to reading only the first failing job per run until the failure is resolved.`,
      );
    }

    return truncated;
  }

  onRunReadComplete(): void {
    this.state.runReadsTotal++;
    const runTokens = this.state.currentRunJobReads.reduce(
      (sum, j) => sum + j.tokensEstimated, 0,
    );

    if (runTokens > this.maxLogLinesPerRun * this.tokensPerLine) {
      const heaviestJob = this.state.currentRunJobReads
        .sort((a, b) => b.tokensEstimated - a.tokensEstimated)[0];
      console.warn(
        `GHAJobLogGuard: run ${this.state.runReadsTotal} log read consumed ${runTokens.toLocaleString()} tokens. ` +
        `Heaviest job: ${heaviestJob?.jobName} (${heaviestJob?.tokensEstimated.toLocaleString()} tokens). ` +
        `Consider reading only the primary failing job on the next iteration.`,
      );
    }

    this.state.currentRunJobReads = [];
  }

  get summary(): JobLogState {
    return { ...this.state };
  }
}

GHAJobLogGuard processes each job's raw log content before injecting it into the agent's context. The critical configuration option is readPassingJobs: false — by default, the guard skips log content for jobs that passed, reducing per-run log volume by 40–70% when most jobs succeed. The maxLogLinesPerJob ceiling (default 200 lines) truncates verbose jobs: it keeps the first 30 lines (job setup context) and the last 170 lines (where errors appear), dropping the middle (verbose npm install output, jest progress dots, webpack progress percentages). The maxCumulativeLogTokens ceiling across the full session provides a hard stop when log accumulation dominates context cost.

Pattern 3: Matrix Build Context Explosion

GitHub Actions' strategy.matrix feature multiplies a set of job steps across a combination of parameters: Node.js versions, operating systems, Python versions, database backends, or any other axis the team wants to test. A common matrix tests node-version: [18, 20, 22] across os: [ubuntu-latest, windows-latest, macos-latest], producing 9 runner instances that each execute the full test suite independently. From a CI correctness standpoint, matrix testing is high-value: it catches platform-specific bugs and version compatibility regressions that single-environment runs miss.

From an AI agent cost standpoint, matrix testing produces a log explosion per iteration. When an agent's code change fails the matrix, some combination of matrix entries fail — typically the failures cluster by failure type rather than by matrix dimension, so a TypeScript compatibility bug that affects all Node.js versions will produce 9 failing jobs, each generating a structurally identical 800-line log with the same TypeScript errors. The agent needs to read one of these logs to understand the failure, but if it retrieves all 9 (or even all 4 failing ones in a partial failure), it injects 4–9× the necessary log content.

The compounding factor is matrix cross-product growth. Teams expand matrices over time as they add platform targets. A 2×2 matrix (2 Node.js versions × 2 OS) produces 4 instances. Adding a third Node.js version (3×2) produces 6. Adding a macOS target (3×3) produces 9. Adding a Python interop test axis (3×3×2) produces 18. Each matrix expansion multiplies the log volume that an AI agent reads per iteration proportionally. A team that iterates with an AI coding agent on a repository with an 18-entry matrix receives 18× the log volume of a single-runner workflow — consuming 18× the token budget for the read step per iteration cycle.

interface MatrixEntry {
  jobId: number;
  jobName: string;
  matrixValues: Record<string, string>;  // { 'node-version': '18', 'os': 'ubuntu-latest' }
  conclusion: 'success' | 'failure' | 'skipped' | 'cancelled' | null;
  logLines?: number;
}

interface MatrixAnalysis {
  totalEntries: number;
  failingEntries: MatrixEntry[];
  representativeFailure: MatrixEntry | null;
  failurePattern: 'all' | 'partial-os' | 'partial-version' | 'isolated';
  tokensIfReadAll: number;
  tokensIfReadOne: number;
}

class GHAMatrixGuard {
  constructor(
    private readonly maxMatrixEntriesPerRead: number = 2,
    private readonly tokensPerLogLine: number = 4,
    private readonly avgLinesPerJob: number = 800,
  ) {}

  analyzeMatrix(entries: MatrixEntry[]): MatrixAnalysis {
    const failingEntries = entries.filter(e => e.conclusion === 'failure');
    const totalEntries = entries.length;

    const failurePattern = this.detectPattern(failingEntries, totalEntries);
    const representativeFailure = this.pickRepresentative(failingEntries, failurePattern);

    const avgLines = failingEntries[0]?.logLines ?? this.avgLinesPerJob;
    const tokensIfReadAll = failingEntries.length * avgLines * this.tokensPerLogLine;
    const tokensIfReadOne = avgLines * this.tokensPerLogLine;

    return {
      totalEntries, failingEntries, representativeFailure,
      failurePattern, tokensIfReadAll, tokensIfReadOne,
    };
  }

  selectJobsToRead(entries: MatrixEntry[]): MatrixEntry[] {
    const analysis = this.analyzeMatrix(entries);
    const { failingEntries, failurePattern, representativeFailure } = analysis;

    if (failurePattern === 'all' && representativeFailure) {
      return [representativeFailure];
    }

    if (failurePattern === 'partial-os') {
      const osGroups = this.groupBy(failingEntries, e => e.matrixValues['os'] ?? 'unknown');
      return Object.values(osGroups).map(group => group[0]).filter(Boolean) as MatrixEntry[];
    }

    if (failurePattern === 'partial-version') {
      const versionGroups = this.groupBy(
        failingEntries,
        e => e.matrixValues['node-version'] ?? e.matrixValues['python-version'] ?? 'unknown',
      );
      return Object.values(versionGroups).map(group => group[0]).filter(Boolean) as MatrixEntry[];
    }

    return failingEntries.slice(0, this.maxMatrixEntriesPerRead);
  }

  private detectPattern(failing: MatrixEntry[], total: number): MatrixAnalysis['failurePattern'] {
    if (failing.length === total) return 'all';
    if (failing.length === 1) return 'isolated';

    const osValues = new Set(failing.map(e => e.matrixValues['os']));
    const allOsValues = new Set(['ubuntu-latest', 'windows-latest', 'macos-latest']);
    if (osValues.size < allOsValues.size && failing.length > 1) return 'partial-os';

    return 'partial-version';
  }

  private pickRepresentative(
    failing: MatrixEntry[],
    pattern: MatrixAnalysis['failurePattern'],
  ): MatrixEntry | null {
    if (failing.length === 0) return null;
    const preferred = failing.find(e => e.matrixValues['os'] === 'ubuntu-latest');
    return preferred ?? failing[0];
  }

  private groupBy<T>(arr: T[], keyFn: (item: T) => string): Record<string, T[]> {
    return arr.reduce((acc, item) => {
      const key = keyFn(item);
      (acc[key] = acc[key] ?? []).push(item);
      return acc;
    }, {} as Record<string, T[]>);
  }
}

GHAMatrixGuard analyzes the matrix job results and selects the minimum representative set of job logs to read. The key method is selectJobsToRead(entries): when all matrix entries fail with the same error (pattern all), it returns one representative entry — the ubuntu-latest run if available, since that log format is most readable. When failures cluster by OS (pattern partial-os), it returns one representative per failing OS. When failures cluster by Node.js version (pattern partial-version), it returns one per failing version. This selection logic typically reduces log reads from the full failing matrix count to 1–3 jobs, cutting per-iteration log token cost by 60–89%.

Pattern 4: CI Feedback Loop Amplification

The preceding three patterns describe cost at the infrastructure layer: how many workflows trigger, how many job logs accumulate, how many matrix instances generate logs. The fourth pattern describes cost at the agent loop layer: what happens when the CI feedback signal doesn't cause the agent to converge, and the agent continues iterating against a failure it cannot fix in the expected number of cycles.

CI feedback loop amplification occurs when the failure the CI is detecting is not in the code the agent is changing. The most common causes are: an environment dependency that changed in the CI image (a package updated upstream), a flaky test that fails non-deterministically (the agent's fix doesn't change the test, so the test continues to fail or pass randomly), a configuration file the agent cannot see (secrets, environment variables, runner-specific settings), or a fundamental architecture mismatch (the agent is fixing TypeScript types but the real failure is a missing API endpoint the test calls). In each case, the agent reads the same or similar log output at every iteration, generates a fix that addresses the visible error text, pushes, and sees the same failure. This loop does not converge because the root cause is outside the agent's code change scope.

The cost signature of an amplified feedback loop is log token entropy remaining high across iterations. When the agent is making real progress, successive run logs show the total error count decreasing (50 errors → 30 errors → 12 errors → 0 errors). When the loop is amplified by an external cause, the error count stays flat or oscillates: iteration 1 shows 3 failing tests, iteration 2 shows 3 failing tests (different tests — flaky), iteration 3 shows 3 failing tests (original tests again). The agent may not recognize this oscillation as a signal to stop, because each iteration's specific error output is slightly different and the agent interprets each difference as indicating partial progress.

interface RunResult {
  runId: number;
  conclusion: 'success' | 'failure' | 'cancelled';
  failingJobCount: number;
  failingTestCount: number;
  errorFingerprints: string[];   // normalized error signatures, not raw text
  committedSha: string;
  timestamp: Date;
}

interface FeedbackLoopState {
  iterationCount: number;
  runHistory: RunResult[];
  convergingTrend: boolean;
  oscillationDetected: boolean;
  consecutiveFlatsCount: number;
  flakySuspectTests: string[];
}

class GHACIFeedbackLoopGuard {
  private state: FeedbackLoopState = {
    iterationCount: 0,
    runHistory: [],
    convergingTrend: true,
    oscillationDetected: false,
    consecutiveFlatsCount: 0,
    flakySuspectTests: [],
  };

  constructor(
    private readonly maxIterations: number = 10,
    private readonly maxConsecutiveFlats: number = 3,
    private readonly convergenceThreshold: number = 0.8,  // errors must drop by 20%+ to count as converging
  ) {}

  onRunComplete(result: RunResult): void {
    this.state.iterationCount++;
    this.state.runHistory.push(result);

    if (result.conclusion === 'success') {
      return;
    }

    if (this.state.iterationCount > this.maxIterations) {
      throw new Error(
        `GHACIFeedbackLoopGuard: ${this.maxIterations} iterations without success. ` +
        `Total failing tests across last 3 runs: ` +
        `${this.state.runHistory.slice(-3).map(r => r.failingTestCount).join(' → ')}. ` +
        `This loop is not converging. Halt and diagnose the root cause before continuing.`,
      );
    }

    this.detectOscillation();
    this.detectFlatLine(result);

    if (this.state.oscillationDetected) {
      const suspectSummary = this.state.flakySuspectTests.slice(0, 5).join(', ');
      throw new Error(
        `GHACIFeedbackLoopGuard: error fingerprint oscillation detected across ` +
        `${this.state.runHistory.length} iterations. ` +
        `The same errors are reappearing in different combinations. ` +
        `Likely cause: flaky tests (suspects: ${suspectSummary || 'unknown'}), ` +
        `environment dependency change, or unreachable external service. ` +
        `These failures are outside the agent's code change scope — ` +
        `disable the flaky tests, re-run without code changes to confirm environment stability, ` +
        `or escalate to human review.`,
      );
    }

    if (this.state.consecutiveFlatsCount >= this.maxConsecutiveFlats) {
      throw new Error(
        `GHACIFeedbackLoopGuard: ${this.state.consecutiveFlatsCount} consecutive runs ` +
        `without error reduction (stuck at ~${result.failingTestCount} failing tests). ` +
        `The agent's changes are not addressing the root cause. ` +
        `Halt iteration and review whether the failure is in the agent's change scope.`,
      );
    }
  }

  private detectOscillation(): void {
    if (this.state.runHistory.length < 3) return;

    const last3 = this.state.runHistory.slice(-3);
    const fingerprintSets = last3.map(r => new Set(r.errorFingerprints));

    const run1And3Overlap = [...fingerprintSets[0]]
      .filter(fp => fingerprintSets[2].has(fp));

    const run2HasDifferent = [...fingerprintSets[1]]
      .some(fp => !fingerprintSets[0].has(fp) && !fingerprintSets[2].has(fp));

    if (run1And3Overlap.length > 0 && run2HasDifferent) {
      this.state.oscillationDetected = true;
      this.state.flakySuspectTests = run1And3Overlap;
    }
  }

  private detectFlatLine(current: RunResult): void {
    if (this.state.runHistory.length < 2) {
      this.state.consecutiveFlatsCount = 0;
      return;
    }

    const previous = this.state.runHistory[this.state.runHistory.length - 2];
    const improvementRatio =
      previous.failingTestCount === 0
        ? 1
        : 1 - current.failingTestCount / previous.failingTestCount;

    if (improvementRatio < (1 - this.convergenceThreshold)) {
      this.state.consecutiveFlatsCount++;
    } else {
      this.state.consecutiveFlatsCount = 0;
    }
  }

  normalizeErrorFingerprint(errorText: string): string {
    return errorText
      .replace(/line \d+/gi, 'line N')
      .replace(/column \d+/gi, 'col N')
      .replace(/\b\d{4,}\b/g, 'N')
      .replace(/\/[^\s"']+\.(ts|js|tsx|jsx)/g, 'FILE')
      .trim()
      .slice(0, 120);
  }

  get summary(): FeedbackLoopState {
    return { ...this.state };
  }
}

GHACIFeedbackLoopGuard tracks convergence by comparing normalized error fingerprints across iterations rather than raw log text. Call normalizeErrorFingerprint(errorText) on each unique error line before storing it — stripping line numbers, column numbers, file paths, and large integers produces a canonical error signature that is stable across partial fixes and noise changes. The oscillation detector looks for runs where the same fingerprints reappear in alternating order, which is the characteristic signature of flaky tests. The flat-line detector catches cases where error count is not decreasing meaningfully across successive iterations — the convergenceThreshold: 0.8 default requires a 20%+ reduction in failing test count to count as a converging iteration.

Combining the Guards: Agent CI Loop Architecture

The four guards address cost at different layers of the agent–CI interaction: fan-out at the workflow trigger layer, log accumulation at the job log retrieval layer, matrix explosion at the log selection layer, and non-convergence at the iteration loop layer. In production, they compose into a single agent loop wrapper that enforces all four ceilings simultaneously.

async function runAgentCILoop(
  agent: CodingAgent,
  repo: { owner: string; name: string },
  task: string,
  options = {
    maxIterations: 8,
    maxRunnerMinutes: 80,
    maxLogTokens: 60_000,
  },
): Promise<'success' | 'halted'> {
  const fanOutGuard = new GHAFanOutGuard(
    options.maxIterations, 40, options.maxRunnerMinutes,
  );
  const logGuard = new GHAJobLogGuard(200, 800, options.maxLogTokens);
  const matrixGuard = new GHAMatrixGuard(2, 4, 800);
  const loopGuard = new GHACIFeedbackLoopGuard(options.maxIterations, 3);

  let codeContext = await agent.readRelevantFiles(task);

  for (let i = 0; i < options.maxIterations; i++) {
    const fix = await agent.generateFix(task, codeContext);
    const sha = await agent.commit(fix);

    const expectedWorkflows = await countMatchingWorkflows(repo);
    fanOutGuard.onAgentCommit(sha, expectedWorkflows);

    const runId = await waitForWorkflowRun(repo, sha);
    const jobs = await listJobsForRun(repo, runId);

    const matrixJobsToRead = matrixGuard.selectJobsToRead(jobs);
    let logContext = '';

    for (const job of matrixJobsToRead) {
      const rawLog = await getJobLog(repo, job.jobId);
      logContext += logGuard.processJobLog(
        job.jobId, job.jobName, job.conclusion, rawLog,
      );
    }
    logGuard.onRunReadComplete();

    const result = summarizeRunResult(jobs, sha, logGuard);
    loopGuard.onRunComplete(result);

    if (result.conclusion === 'success') {
      return 'success';
    }

    codeContext = updateContextWithLogs(codeContext, logContext);
  }

  return 'halted';
}

The integrated loop places all four guards in sequence at their natural intervention points: fan-out is checked immediately after each commit before waiting for the run; log selection happens before API calls for job logs; log injection happens as each job log is processed; convergence is evaluated after each run completes. Any guard raising terminates the loop with a structured error message that identifies the specific ceiling hit and the recommended recovery action — rather than letting the loop exhaust its iteration budget before failing.