Review Loop Session Architecture in no-mistakes: Managing Reviewer and Fixer Sessions

The no-mistakes pipeline isolates reviewer and fixer roles into separate, durable agent sessions, ensuring the adversarial reviewer never shares state with the fixer during code review iterations.

The no-mistakes repository implements a rigorous review loop that alternates between adversarial review and automated fixing. According to the project's AGENTS.md specification, this architecture relies on distinct session lifecycles for each role to maintain unbiased evaluation. Understanding this review loop session architecture is essential for operators configuring self-hosted instances or debugging agent behavior.

Core Session Architecture

The pipeline manages two discrete session types that persist across different phases of a single run.

The Reviewer Session

One durable reviewer session spans the initial adversarial review and every subsequent full rereview. This session accumulates context about the codebase and previous findings, but never encounters fix-specific rationale. In internal/pipeline/sessions.go, the executor retrieves this session using the RoleReviewer constant when entering review phases.

The Fixer Session

A separate fixer session handles all review-fix turns within the same run. This isolation ensures that the agent applying changes operates without polluting the reviewer's state. As documented in AGENTS.md, the fixer session is created fresh for the fix-review phase and persists across iterations of the fix-verify loop, keyed separately in the database.

Session Isolation Guarantees

The architecture enforces that roles never share a session. According to the source documentation, this prevents the reviewer from inheriting the fixer's rationale and vice-versa. The invariant guarantees that the reviewer evaluates code as-is without being influenced by the fixes it just generated, maintaining adversarial integrity.

Implementation Details

Database Schema and Role-Based Lookup

Session metadata persists in internal/db/agent_session.go, where rows are keyed by RunID and Role (reviewer versus fixer). The schema ensures that each run retrieves the correct session without cross-contamination between independent executions.

When the executor starts a step, it calls the store layer with the specific role enum. If a record exists, the pipeline resumes the existing session; otherwise, it instantiates a new agent instance and writes the metadata to the database.

Pipeline Session Management

The core logic in internal/pipeline/sessions.go implements a session_reuse configuration flag. When set to false, the system forces a cold start for each role, discarding any existing session state and guaranteeing fresh isolation. This flag is checked during the getAgentSession resolution phase before the executor invokes the underlying LLM.

Review Fixer Verification Discipline

The AGENTS.md specification mandates strict constraints on the fixer session's behavior. The fixer must apply all fixes before one focused verification and is explicitly forbidden from running the whole repository test or lint suite during the fix round. This discipline prevents the fixer session from consuming excessive context window or tainting its state with unrelated diagnostic output.

Code Example: Session Lifecycle in Practice

The following Go snippets illustrate how the pipeline creates and retrieves role-specific sessions. These patterns are implemented in internal/pipeline/sessions.go and internal/db/agent_session.go.

// Retrieve the session for the current step.
// `role` is either types.RoleReviewer or types.RoleFixer.
func getAgentSession(ctx context.Context, db *db.DB, runID string, role types.AgentRole) (*db.AgentSession, error) {
    // Try to fetch an existing session for this run & role.
    sess, err := db.AgentSession.FindByRunAndRole(ctx, runID, role)
    if err == nil && sess != nil {
        return sess, nil // reuse existing session
    }

    // No session yet – create a fresh one.
    newSess := &db.AgentSession{
        RunID:   runID,
        Role:    role,
        // The underlying agent (e.g., codex, claude) is instantiated here.
        // Session reuse is disabled unless the config explicitly enables it.
    }
    if err := db.AgentSession.Insert(ctx, newSess); err != nil {
        return nil, err
    }
    return newSess, nil
}

When executing a review step, the pipeline passes RoleReviewer:

func runReviewStep(ctx context.Context, exec *Executor) error {
    sess, err := getAgentSession(ctx, exec.DB, exec.Run.ID, types.RoleReviewer)
    if err != nil {
        return err
    }
    // Use sess.Agent to invoke the reviewer LLM.
    findings, err := sess.Agent.Review(ctx, exec.Diff)
    // Process findings without affecting fixer state...
    return nil
}

Conversely, the fixer step uses RoleFixer to retrieve the isolated fixer session:

func runFixReviewStep(ctx context.Context, exec *Executor) error {
    sess, err := getAgentSession(ctx, exec.DB, exec.Run.ID, types.RoleFixer)
    if err != nil {
        return err
    }
    // The fixer LLM receives the same diff but a clean session context.
    fixes, err := sess.Agent.Fix(ctx, exec.Diff, exec.Findings)
    // Apply fixes without reviewer context contamination...
    return nil
}

Key Files and Their Responsibilities

• internal/pipeline/sessions.go: Contains the getAgentSession logic and session_reuse flag handling that determines whether to instantiate a new agent or resume an existing one.
• internal/db/agent_session.go: Defines the database schema for AgentSession records, including RunID and Role indexing, ensuring durable storage across process restarts.
• AGENTS.md: Documents the architectural invariants, including the Review Loop Agent Sessions section and Review Fixer Verification Discipline constraints.

Summary

• The reviewer session is durable across initial and rereview phases, while the fixer session is separate and isolated.
• Roles never share session state, preventing rationale contamination between adversarial review and automated fixing.
• The session_reuse configuration flag forces cold starts when set to false, guaranteeing fresh isolation for sensitive runs.
• Session persistence uses a composite key of RunID and Role in internal/db/agent_session.go, enabling crash recovery without cross-run leakage.
• Fixer sessions operate under strict verification discipline, applying all fixes before focused validation without running full repository test suites.

Frequently Asked Questions

Why does no-mistakes use separate sessions for reviewers and fixers?

Separate sessions prevent the reviewer from being influenced by the fixer's internal reasoning or previous change attempts. According to AGENTS.md, this isolation ensures the reviewer evaluates the code objectively as-is, maintaining the adversarial integrity of the review loop.

How does the session_reuse configuration affect the review loop?

When session_reuse is set to false in the configuration, the pipeline forces a cold start for both reviewer and fixer sessions, discarding any existing state. This guarantees fresh context for each run but increases initialization overhead, as implemented in internal/pipeline/sessions.go.

Where is session state persisted during a review run?

Session state is stored in the database via internal/db/agent_session.go. Records are keyed by the unique RunID and the agent Role (reviewer or fixer), allowing the executor to resume the correct session after crashes or process restarts without mixing contexts between different runs.

What prevents reviewer bias from fixer-generated changes?

The architecture enforces that reviewer and fixer sessions never share a session ID or context window. The reviewer session is retrieved separately using types.RoleReviewer, while fixer changes are applied in a distinct types.RoleFixer session. This hard separation ensures the reviewer does not see the fixer's draft changes or rationale during evaluation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}