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

> Understand the review loop session architecture in no-mistakes. Discover how separate agent sessions manage reviewer and fixer roles to prevent state sharing for better code review.

- Repository: [Kun Chen/no-mistakes](https://github.com/kunchenguid/no-mistakes)
- Tags: architecture
- Published: 2026-07-18

---

**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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/pipeline/sessions.go) and [`internal/db/agent_session.go`](https://github.com/kunchenguid/no-mistakes/blob/main/internal/db/agent_session.go).

```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`:

```go
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:

```go
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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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`](https://github.com/kunchenguid/no-mistakes/blob/main/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.