executor

type AgentExecutor struct {
	// Bin is the agent executable. Default: $TQ_AGENT_BIN, $TQ_CRUSH_BIN or
	// "crush". Point it at a stub in tests.
	Bin string
	// ProjectsDir resolves relative Repo names in payloads ("demo" →
	// <ProjectsDir>/demo). Absolute Repo paths bypass it.
	ProjectsDir string
	// Yolo is the operator-level autonomy request (pool start). crush run
	// has no yolo flag; see AgentPayload.Yolo for how autonomy is actually
	// granted (repo-local crush config). Fail closed, never silently.
	Yolo bool
	// MaxConcurrent caps how many agent processes run at once MACHINE-WIDE
	// (flock'd slot files shared across every tq process on the host; 0 =
	// uncapped). Caps cost when several pools share a machine.
	MaxConcurrent int
	// CloseoutPrompt, when set, gives every agent task a SECOND conversation
	// turn: after the work turn ends, the same session receives this prompt
	// (the owner's brutal self-review + status report) before verify runs.
	// Empty = off (single turn, pinned argv contract unchanged).
	CloseoutPrompt string
	// contains filtered or unexported fields
}

type AgentPayload struct {
	// Repo is the repository the agent works in: a name resolved against the
	// executor's ProjectsDir, or an absolute path. Required.
	Repo string `json:"repo"`
	// Prompt is the full instruction for the agent run. Required.
	Prompt string `json:"prompt"`
	// Model optionally overrides the crush model ("provider/model").
	Model string `json:"model,omitempty"`
	// V is the payload contract version. Zero decodes
	// as v1; a version above what this binary understands fails fast as a
	// permanent error instead of misparsing newer fields.
	V int `json:"v,omitempty"`
	// Session optionally continues a previous crush session by ID.
	Session string `json:"session,omitempty"`
	// Dedup is the harvester's item key; purely informational, used to keep
	// TODO items and tasks 1:1 across harvest runs.
	Dedup string `json:"dedup,omitempty"`
	// Item is the raw TODO_LIST work item the prompt was rendered from;
	// purely informational. Status windows pin it so report excerpts show
	// the real work instead of the prompt template's first line. Empty for
	// tasks minted outside the harvester.
	Item string `json:"item,omitempty"`
	// Verify is a shell command that must exit 0 after the agent run for the
	// task to complete — the enforced quality gate. Empty means auto-detect:
	// Go repositories (go.mod present) run "go build ./... && go test ./...
	// -count=1", everything else runs nothing.
	Verify string `json:"verify,omitempty"`
	// RequireClean refuses to start unless the repo's git tree is clean, so
	// the pool never tramples human work-in-progress. Default true. Repos
	// without a .git directory skip the check (nothing to protect).
	RequireClean *bool `json:"require_clean,omitempty"`
	// TimeoutMinutes caps the whole task (agent run + verify). Default 30.
	// The worker's task timeout still applies as a hard ceiling above this.
	TimeoutMinutes int `json:"timeout_minutes,omitempty"`
	// Yolo marks this task's agent as autonomous. crush run has NO yolo
	// flag (verified against crush v0.92: "Unknown flag: --yolo"); autonomy
	// comes from the repo's own project-local crush config granting
	// permissions (`.crushrc`: `permissions allow view ls grep edit write bash`).
	// This field makes the executor fail fast with remediation guidance when
	// autonomy is requested but the repo has no such config, instead of
	// burning agent attempts on runs that stall on permission prompts.
	Yolo bool `json:"yolo,omitempty"`
}

type AgentResult struct {
	// SessionID is the crush session id, best-effort extracted from the
	// agent's output (`crush run` prints it; formats vary between
	// versions — absent when nothing matches).
	SessionID string `json:"session_id,omitempty"`
	// VerifyTail is the last lines of the verify command's output: the
	// proof the task completed on.
	VerifyTail string `json:"verify_tail,omitempty"`
	// FilesChanged and CommitSHA are the agent's own structured report,
	// parsed from a final `TQ_RESULT: {"files_changed": [...], "commit_sha":
	// "..."}` output line (the agent prompt convention). Absent when the
	// agent did not emit one.
	FilesChanged []string `json:"files_changed,omitempty"`
	CommitSHA    string   `json:"commit_sha,omitempty"`
	// LogPath is the sidecar file holding the FULL agent + verify output,
	// written when TQ_LOG_DIR is set on the worker/pool. Absent otherwise.
	LogPath string `json:"log_path,omitempty"`
}

type CommandExecutor struct {
	Template string
	// MemoryLimitMB caps the shell process's virtual memory via
	// `ulimit -v` (POSIX sh; 0 = uncapped). Bounds runaway payloads on
	// shared machines — the queue keeps serving while the task dies fast.
	MemoryLimitMB int
	// Nice lowers scheduling priority via `nice -n` (0 = unchanged).
	// Interactive work wins CPU; queue work yields.
	Nice int
}

type DLQFixExecutor struct {
	// Agent supplies the run mechanics and its configuration (Bin,
	// ProjectsDir, Yolo). nil selects a default AgentExecutor.
	Agent *AgentExecutor
}

type DLQFixPayload struct {
	// Repo is the repository the dead task ran in (same resolution rules as
	// AgentPayload.Repo). Required.
	Repo string `json:"repo"`
	// DeadTask is the dead task's queue id — lineage for `tq show` and the
	// sweeper's disposition target. Required.
	DeadTask string `json:"dead_task"`
	// DeadType is the dead task's type (the mint rule scopes autopsies to
	// agent tasks; the field rides along for the prompt and forensics).
	DeadType string `json:"dead_type,omitempty"`
	// Work is what the dead task was asked to do: the agent prompt, with
	// its {{TASK_ID}} placeholders already resolved the way the dead run
	// saw them. Required.
	Work string `json:"work"`
	// Failure is the structured forensics from the dead task's LAST
	// task.failed fact (stage, exit code, output tail). Zero when the
	// journal predates failure evidence.
	Failure FailureEvidence `json:"failure,omitempty"`
	// LastError is the dead task record's error text.
	LastError string `json:"last_error,omitempty"`
	// Attempts is how many attempts the dead task burned.
	Attempts int `json:"attempts,omitempty"`
	// Model optionally overrides the crush model for the autopsy.
	Model string `json:"model,omitempty"`
	// Yolo marks the autopsy as autonomous (same contract as
	// AgentPayload.Yolo: needs a repo-local crush config granting
	// permissions). Mints mirror the dead task's autonomy.
	Yolo bool `json:"yolo,omitempty"`
	// RequireClean defaults FALSE for autopsies, deliberately: a dead
	// agent's uncommitted partial work IS evidence, and a clean-tree
	// preflight would requeue the autopsy forever on exactly the cases the
	// feature exists for. The repo's .git absence skips the check as
	// usual. Minted payloads pin the false explicitly.
	RequireClean *bool `json:"require_clean,omitempty"`
	// TimeoutMinutes caps the autopsy run. Default 30 (a diagnosis is a
	// full work turn: read code, maybe reproduce, maybe fix).
	TimeoutMinutes int `json:"timeout_minutes,omitempty"`
}

type DLQFixResult struct {
	Verdict DLQFixVerdict `json:"verdict"`
	// Summary is the diagnosis: for fixed, the root cause and the change;
	// for wontfix, the reason the task is unfixable from the repo.
	Summary string `json:"summary"`
	// CommitSHA is the fix commit the autopsy landed ("" for wontfix, or a
	// fixed diagnosis that needed no repo change).
	CommitSHA string `json:"commit_sha,omitempty"`
	// SessionID is the crush session id, same convention as AgentResult.
	SessionID string `json:"session_id,omitempty"`
	// LogPath is the sidecar file with the full autopsy output (written
	// when TQ_LOG_DIR is set), same convention as AgentResult.
	LogPath string `json:"log_path,omitempty"`
}

type DLQFixVerdict string

type Executor interface {
	Execute(ctx context.Context, t task.Task) error
}

type FailureEvidence struct {
	Stage    string `json:"stage"`               // "agent", "verify" or "command"
	ExitCode int    `json:"exit_code,omitempty"` // process exit code (0 when the error was not an exit)
	Tail     string `json:"tail,omitempty"`      // last lines of the failing output
}

type Func func(ctx context.Context, t task.Task) error

type HTTPExecutor struct {
	URL    string
	Client *http.Client
}

type LeaseLostError struct{ Cause error }

type PermanentError struct{ Cause error }

type PreflightError struct{ Cause error }

type PrioritizeExecutor struct {
	// Agent supplies the run mechanics and its configuration. nil selects
	// a default AgentExecutor.
	Agent *AgentExecutor
}

type PrioritizeItem struct {
	Key     string `json:"key"`
	Text    string `json:"text"`
	Heading string `json:"heading,omitempty"`
}

type PrioritizePayload struct {
	// Repo is the repository whose TODO_LIST the items come from (same
	// resolution rules as AgentPayload.Repo). The scorer reads it for
	// context (AGENTS.md, code layout) but changes nothing. Required.
	Repo string `json:"repo"`
	// RepoName is the display name of the repo.
	RepoName string `json:"repo_name,omitempty"`
	// Items is the batch to score. Required, non-empty.
	Items []PrioritizeItem `json:"items"`
	// Model optionally overrides the crush model; empty reuses the repo's
	// .crushrc (the default and recommended setting — model+effort live
	// ONLY there, ADR/pool contract).
	Model string `json:"model,omitempty"`
	// Yolo marks the scorer as autonomous (same contract as
	// AgentPayload.Yolo).
	Yolo bool `json:"yolo,omitempty"`
	// RequireClean refuses to start on a dirty tree. Default true — the
	// scorer reads the repo for context and should see committed state.
	RequireClean *bool `json:"require_clean,omitempty"`
	// TimeoutMinutes caps the run. Default 10 (scoring reads; it does not
	// build).
	TimeoutMinutes int `json:"timeout_minutes,omitempty"`
}

type PrioritizeResult struct {
	Verdicts  []PrioritizeVerdict `json:"verdicts"`
	SessionID string              `json:"session_id,omitempty"`
	LogPath   string              `json:"log_path,omitempty"`
}

type PrioritizeVerdict struct {
	ItemKey       string `json:"item_key"`
	Score         int    `json:"score"`
	EffortMinutes int    `json:"effort_minutes,omitempty"`
	Confidence    int    `json:"confidence,omitempty"`
	Reasoning     string `json:"reasoning,omitempty"`
}

type RateLimitError struct {
	Cause error
	// RetryAfter is how long to wait before the next attempt. Always
	// positive; capped by maxRateLimitWait.
	RetryAfter time.Duration
}

type Registry struct {
	// contains filtered or unexported fields
}

type ReviewExecutor struct {
	// Agent supplies the run mechanics and its configuration (Bin,
	// ProjectsDir, Yolo). nil selects a default AgentExecutor.
	Agent *AgentExecutor
}

type ReviewFinding struct {
	// Title is the one-line summary; it keys the dedup of auto-minted fix
	// tasks, so keep findings stable in wording across re-reviews.
	Title string `json:"title"`
	// Severity is a display hint normalized to low/medium/high at parse
	// time (unknown or empty ratings degrade to medium — severity never
	// gates anything mechanically, so leniency here is safe).
	Severity string `json:"severity,omitempty"`
	// Detail is the free-form explanation and suggested direction.
	Detail string `json:"detail,omitempty"`
}

type ReviewPayload struct {
	// Repo is the repository the change landed in (same resolution rules as
	// AgentPayload.Repo). Required.
	Repo string `json:"repo"`
	// ReviewedTask is the queue task ID under review — lineage for `tq show`
	// and the sweeper's loop guard. Required.
	ReviewedTask string `json:"reviewed_task"`
	// Item is the original instruction the reviewed agent was given: the bar
	// the change is judged against. Required.
	Item string `json:"item"`
	// CommitSHA is the commit the reviewed agent reported (from its
	// TQ_RESULT self-report). Empty when the agent landed no commit; the
	// reviewer then inspects the repo's latest state instead.
	CommitSHA string `json:"commit_sha,omitempty"`
	// FilesChanged lists the files the reviewed agent reported touching.
	FilesChanged []string `json:"files_changed,omitempty"`
	// Extra carries operator focus instructions appended to the prompt.
	Extra string `json:"extra,omitempty"`
	// Model optionally overrides the crush model for the reviewer.
	Model string `json:"model,omitempty"`
	// Yolo marks the reviewer as autonomous (same contract as
	// AgentPayload.Yolo: needs a repo-local crush config granting
	// permissions). Pools typically mirror the reviewed task's autonomy.
	Yolo bool `json:"yolo,omitempty"`
	// RequireClean refuses to start unless the repo tree is clean — a
	// reviewer must judge the committed state, not dirty work-in-progress.
	// Default true. Same escape hatch as AgentPayload.
	RequireClean *bool `json:"require_clean,omitempty"`
	// TimeoutMinutes caps the review run. Default 15 (reviews read; they do
	// not rebuild the world).
	TimeoutMinutes int `json:"timeout_minutes,omitempty"`
}

type ReviewResult struct {
	Verdict   ReviewVerdict   `json:"verdict"`
	Summary   string          `json:"summary,omitempty"`
	Findings  []ReviewFinding `json:"findings,omitempty"`
	SessionID string          `json:"session_id,omitempty"`
	// LogPath is the sidecar file with the full reviewer output (written
	// when TQ_LOG_DIR is set), same convention as AgentResult.
	LogPath string `json:"log_path,omitempty"`
}

type ReviewVerdict string

type Sink struct {
	// contains filtered or unexported fields
}

type StatusCompletion struct {
	TaskID      string   `json:"task_id"`
	Item        string   `json:"item"`
	Commit      string   `json:"commit,omitempty"`
	Files       []string `json:"files,omitempty"`
	CompletedAt string   `json:"completed_at,omitempty"`
}

type StatusExecutor struct {
	// Agent supplies the run mechanics and its configuration. nil selects a
	// default AgentExecutor.
	Agent *AgentExecutor
}

type StatusPayload struct {
	// Repo is the repository being reported on (same resolution rules as
	// AgentPayload.Repo). Required.
	Repo string `json:"repo"`
	// Project is the queue project (repo name) the window belongs to.
	// Required; also the sweeper's loop guard identity.
	Project string `json:"project"`
	// Completed lists the agent tasks in this report's window, oldest
	// first. Bounded by the sweeper; never empty for a minted task.
	Completed []StatusCompletion `json:"completed"`
	// Model optionally overrides the crush model for the reporting agent.
	Model string `json:"model,omitempty"`
	// Yolo marks the reporting agent as autonomous (same contract as
	// AgentPayload.Yolo). Pools typically mirror the window's autonomy.
	Yolo bool `json:"yolo,omitempty"`
	// RequireClean refuses to start unless the repo tree is clean — the
	// reporter must not trample work-in-progress, and commits its own
	// report afterwards. Default true. Same escape hatch as AgentPayload.
	RequireClean *bool `json:"require_clean,omitempty"`
	// TimeoutMinutes caps the report run. Default 15.
	TimeoutMinutes int `json:"timeout_minutes,omitempty"`
	// Verify is the repo quality gate that must exit 0 after the report
	// run (the reporter commits, so a broken tree is a real possibility).
	// Empty means the usual resolution: the repo's .tq-verify file, then
	// auto-detection — identical to AgentPayload.Verify.
	Verify string `json:"verify,omitempty"`
}

type StatusResult struct {
	// Report is the repo-relative path of the written status report.
	Report string `json:"report"`
	// NextItems counts the next-work items the agent appended to
	// TODO_LIST.md (its own self-report, not re-verified).
	NextItems int    `json:"next_items"`
	SessionID string `json:"session_id,omitempty"`
	LogPath   string `json:"log_path,omitempty"`
}