How Agent Session Reuse Works in the Review Loop

The no-mistakes pipeline maintains two durable agent sessions per run—one for the reviewer and one for the fixer—reusing the reviewer session across the entire execution by default while isolating the fixer to single cycles, with behavior controlled by the session_reuse configuration flag.

Agent session reuse is a critical durability mechanism in the no-mistakes repository that preserves conversation context across multi-turn review loops. By persisting agent state to the database and reusing connections, the pipeline avoids re-initializing large language model contexts on every turn. Understanding how the session manager orchestrates this reuse reveals how the tool maintains long-running review workflows and survives daemon restarts.

The Two-Session Architecture

The review loop relies on distinct sessions for each agent role, each with different lifetimes:

• Reviewer Session – Initialized once at the start of the pipeline run and retained for the entire duration. This session holds the complete review transcript, allowing the reviewer agent to resume exactly where it left off across multiple review turns.

• Fixer Session – Created fresh for each review-fix cycle. This ensures that fix operations operate on clean state without accumulating history from previous fix attempts.

Both sessions are persisted in the database (internal/db/agent_session.go) as per-run, per-role records. This model enables the pipeline to resume a paused review without losing context, even if the daemon restarts between cycles.

Configuring Session Reuse with the session_reuse Flag

By default, the review loop reuses the reviewer session across the entire run. You can toggle this behavior using the global configuration option session_reuse:

# .no-mistakes.yaml

session_reuse: true   # default: maintains a warm reviewer session

When session_reuse is set to false, the runtime forces a cold reviewer session for each turn. According to internal/config/config.go, this flag determines whether the pipeline creates a fresh agent connection for every review iteration or maintains a durable connection. The test suite confirms this behavior in internal/pipeline/sessions_test.go via the TestRunSessions_DisabledRunsCold case, which verifies that disabling reuse prevents session retention.

Implementation Details in the Session Manager

The core logic resides in internal/pipeline/sessions.go, which implements a run-scoped session manager responsible for creation, retrieval, and isolation.

Session Manager Initialization

When a pipeline run starts, the system creates a SessionManager instance scoped to that specific run. As implemented in internal/pipeline/sessions.go (lines 24-33), the manager keys sessions by run ID and role (reviewer or fixer), ensuring that each execution context maintains its own isolated state.

Session Retrieval Logic

Throughout the review steps, the codebase calls SessionManager.GetOrCreate(role) to obtain a session handle:

1. If a session already exists for that role and session_reuse is true, the manager returns the existing session.
2. If session_reuse is false or no session exists, the manager instantiates a fresh session with empty state.

This logic ensures that the reviewer maintains continuity while the fixer receives a clean slate for each cycle.

Persistence Layer

Session durability relies on the database layer defined in internal/db/agent_session.go. The manager writes the session's transcript and metadata to the agent_sessions table, making state survive process restarts. When the daemon resumes a parked run, it retrieves the existing reviewer record from the database rather than starting from scratch.

Role Isolation Guarantees

The implementation enforces strict isolation between agent roles. The reviewer and fixer never share a session instance—the reviewer's transcript cannot be overwritten by fixer operations. As noted in the comments within sessions.go, this separation preserves a clean distinction between analysis (reviewer) and modification (fixer) contexts.

Testing Session Reuse Behavior

The test suite in internal/pipeline/sessions_test.go validates the configuration's impact on session lifecycle:

• TestRunSessions_DisabledRunsCold – Confirms that setting session_reuse: false forces the creation of a new reviewer session on every turn, breaking persistence.
• TestRunSessions_NilManagerRunsCold – Ensures that steps executing outside the review loop context do not attempt to reuse sessions, preventing cross-contamination between unrelated operations.

These tests guarantee that the flag behaves predictably across both enabled and disabled states.

Practical Configuration Examples

To enable session reuse (default behavior):

# .no-mistakes.yaml

session_reuse: true

To force cold reviewer sessions for every turn:

# .no-mistakes.yaml

session_reuse: false

Programmatically, the retrieval pattern looks like this:

mgr := pipeline.NewSessionManager(runID)                    // scoped to current run
revSess, _ := mgr.GetOrCreate(pipeline.RoleReviewer)         // reused if flag true
fixSess, _ := mgr.GetOrCreate(pipeline.RoleFixer)            // fresh each fix turn

This Go snippet illustrates how the session_reuse flag controls whether revSess returns the same persistent object across multiple review rounds or a newly initialized instance.

Summary

• Two-session model – The reviewer session spans the entire run; the fixer session is per-cycle.
• Configurable reuse – The session_reuse flag (default true) in internal/config/config.go controls whether the reviewer session persists.
• Run-scoped management – internal/pipeline/sessions.go implements the SessionManager keyed by run ID and role, with retrieval via GetOrCreate().
• Database durability – Sessions persist in the agent_sessions table (internal/db/agent_session.go), enabling resume after restarts.
• Strict isolation – Reviewer and fixer roles never share session instances, preserving context boundaries.

Frequently Asked Questions

What happens if I disable session_reuse?

Disabling session_reuse forces the pipeline to create a new reviewer session for every review turn. While this increases overhead by re-initializing the agent context each time, it ensures complete isolation between turns. According to internal/pipeline/sessions_test.go, this behavior is validated by the TestRunSessions_DisabledRunsCold test case.

Where is agent session state stored between daemon restarts?

Session state is persisted to the agent_sessions database table, defined in internal/db/agent_session.go. When the daemon restarts and resumes a run, the SessionManager retrieves the existing session record using the run ID and role combination, restoring the transcript and metadata exactly as they existed before the interruption.

Why does the fixer get a new session every cycle while the reviewer keeps one?

The fixer receives a fresh session per cycle to prevent solution attempts from polluting the reviewer's analysis context. This isolation, enforced in internal/pipeline/sessions.go, ensures that the reviewer maintains an objective view of the code while the fixer can experiment with changes without accumulating error history across multiple fix attempts.

Can different pipeline runs share agent sessions?

No, sessions are strictly scoped to a single pipeline run. The SessionManager constructor in internal/pipeline/sessions.go requires a runID parameter, and all session keys incorporate this identifier. This design prevents cross-contamination between concurrent or sequential runs while allowing reuse within the same run.

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