runner

Documentation

Overview

Package runner manages the agent lifecycle including Docker-based task execution, review orchestration, and the top-level poll loop that drives claiming, running, and merging tasks.

Index

• func DryRun(w io.Writer, repoRoot, branch string, opts RunOptions) error
• func PostReviewAction(tasksDir, agentID string, task *queue.ClaimedTask)
• func Run(repoRoot, branch string, opts RunOptions) error
• func SelectAndLockReview(tasksDir string, idx *queueview.PollIndex) (*queue.ClaimedTask, func())
• func SelectTaskForReview(tasksDir string, idx *queueview.PollIndex) *queue.ClaimedTask
• func VerifyReviewBranch(repoRoot, tasksDir string, task *queue.ClaimedTask, agentID string) bool
• type DryRunRenderer
  • func (r *DryRunRenderer) RenderAffectsConflicts(view queueview.RunnableBacklogView)
  • func (r *DryRunRenderer) RenderBacklogSummary(idx *queueview.PollIndex, deferred map[string]struct{}, ...)
  • func (r *DryRunRenderer) RenderDependencyResolution(promotable int)
  • func (r *DryRunRenderer) RenderDependencySummary(tasksDir string, idx *queueview.PollIndex)
  • func (r *DryRunRenderer) RenderExecutionOrder(runnable []*queueview.TaskSnapshot)
  • func (r *DryRunRenderer) RenderQueueSummary(idx *queueview.PollIndex, subdirs []string, parseFailuresByDir map[string]int, ...)
  • func (r *DryRunRenderer) RenderResolvedSettings(opts RunOptions)
  • func (r *DryRunRenderer) RenderValidation(parseFailures []queueview.ParseFailure, totalTasks int)
• type RunMode
• type RunOptions
• type ToolFinding
• type ToolReport
  • func InspectHostTools() ToolReport

Functions

func DryRun

func DryRun(w io.Writer, repoRoot, branch string, opts RunOptions) error

DryRun validates the task queue setup without launching Docker containers. It runs one iteration of queue management (dependency promotion, overlap detection, manifest writing) and reports the results to w, then exits.

func PostReviewAction

func PostReviewAction(tasksDir, agentID string, task *queue.ClaimedTask)

PostReviewAction is the exported entry point for the host-side review handoff after a review agent exits. It delegates to the internal postReviewAction implementation.

func Run

func Run(repoRoot, branch string, opts RunOptions) error

func SelectAndLockReview

func SelectAndLockReview(tasksDir string, idx *queueview.PollIndex) (*queue.ClaimedTask, func())

SelectAndLockReview is the exported entry point for selecting and locking the highest-priority review candidate. It delegates to selectAndLockReview.

func SelectTaskForReview

func SelectTaskForReview(tasksDir string, idx *queueview.PollIndex) *queue.ClaimedTask

SelectTaskForReview is the exported entry point for selecting the highest-priority review candidate. It delegates to selectTaskForReview.

func VerifyReviewBranch

func VerifyReviewBranch(repoRoot, tasksDir string, task *queue.ClaimedTask, agentID string) bool

VerifyReviewBranch checks whether the task branch exists in the host repo before launching a review agent. If the branch is missing it records a review-failure marker and returns false. Returns true when the branch exists and the review may proceed.

Types

type DryRunRenderer

type DryRunRenderer struct {
	W     io.Writer
	Color ui.ColorSet
	Width int
}

DryRunRenderer formats dry-run validation output to a writer with optional color and terminal-width-aware layout.

func (*DryRunRenderer) RenderAffectsConflicts

func (r *DryRunRenderer) RenderAffectsConflicts(view queueview.RunnableBacklogView)

RenderAffectsConflicts writes the === Affects Conflict Detection === section and any dependency-blocked backlog tasks.

func (*DryRunRenderer) RenderBacklogSummary

func (r *DryRunRenderer) RenderBacklogSummary(idx *queueview.PollIndex, deferred map[string]struct{}, blocked map[string][]queueview.DependencyBlock)

RenderBacklogSummary writes the === Backlog Task Summary === section with compact frontmatter for every parsed backlog task.

func (*DryRunRenderer) RenderDependencyResolution

func (r *DryRunRenderer) RenderDependencyResolution(promotable int)

RenderDependencyResolution writes the === Dependency Resolution === section.

func (*DryRunRenderer) RenderDependencySummary

func (r *DryRunRenderer) RenderDependencySummary(tasksDir string, idx *queueview.PollIndex)

RenderDependencySummary writes the === Dependency Summary === section for waiting/ tasks, showing each dependency and its resolved queue state.

func (*DryRunRenderer) RenderExecutionOrder

func (r *DryRunRenderer) RenderExecutionOrder(runnable []*queueview.TaskSnapshot)

RenderExecutionOrder writes the === Execution Order === section showing runnable backlog tasks in priority order with their priority values.

func (*DryRunRenderer) RenderQueueSummary

func (r *DryRunRenderer) RenderQueueSummary(idx *queueview.PollIndex, subdirs []string, parseFailuresByDir map[string]int, deferredCount int)

RenderQueueSummary writes the === Queue Summary === section.

func (*DryRunRenderer) RenderResolvedSettings

func (r *DryRunRenderer) RenderResolvedSettings(opts RunOptions)

RenderResolvedSettings writes the === Resolved Settings === section.

func (*DryRunRenderer) RenderValidation

func (r *DryRunRenderer) RenderValidation(parseFailures []queueview.ParseFailure, totalTasks int)

RenderValidation writes the === Task File Validation === section.

type RunMode

type RunMode int

RunMode controls how long runner.Run keeps polling before exiting.

const (
	// RunModeDaemon is the default long-running polling loop.
	RunModeDaemon RunMode = iota
	// RunModeOnce runs exactly one poll iteration, then exits.
	RunModeOnce
	// RunModeUntilIdle keeps polling until no actionable queue work remains.
	RunModeUntilIdle
)

type RunOptions

type RunOptions struct {
	DockerImage                string
	Mode                       RunMode
	TaskModel                  string
	ReviewModel                string
	ReviewSessionResumeEnabled bool
	TaskReasoningEffort        string
	ReviewReasoningEffort      string
	AgentTimeout               time.Duration
	RetryCooldown              time.Duration
	Verbose                    bool
}

RunOptions holds configuration values for a mato run.

TaskModel, ReviewModel, TaskReasoningEffort, and ReviewReasoningEffort must already be resolved to non-empty values before calling Run or DryRun. DockerImage, AgentTimeout, RetryCooldown, and Mode may be left zero to use downstream defaults.

type ToolFinding

type ToolFinding struct {
	Name     string
	Path     string // resolved path, empty if not found
	Required bool
	Found    bool
	Message  string
}

ToolFinding describes a single tool or directory inspection result.

type ToolReport

type ToolReport struct {
	Findings []ToolFinding
}

ToolReport collects all tool inspection findings.

func InspectHostTools

func InspectHostTools() ToolReport

InspectHostTools probes all host tools and directories, returning structured findings for every item regardless of success or failure. This is a parallel implementation that mirrors the checks in discoverHostTools() but collects findings instead of failing fast. discoverHostTools() is NOT modified.