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
	// ReresolveVerify enables claim-time verify re-resolution: the payload's
	// enqueue-time verify pin is IGNORED and the gate is resolved fresh
	// (.tq-verify file, then auto-detect) — a verify-contract change in the
	// repo can no longer fire a stale pinned command at a task queued before
	// the change (09-39 f3). Default false keeps the payload contract:
	// file > pin > detect.
	ReresolveVerify bool
	// 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"`
	// Items carries the full member list when the task was minted as a
	// BATCH (harvest --batch-items > 1): one task, many work items, one
	// session. Item stays the FIRST member; purely informational.
	Items []string `json:"items,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"`
	// Answered carries the owner's rulings for questions this task asked
	// (PapDashboard questions): the store injects them when the answer
	// unblocks the parked task, and the executor renders them into the
	// prompt so the resumed run honors the decisions instead of re-asking.
	Answered []queue.QuestionAnsweredDetail `json:"answered,omitempty"`
	// RejectedSHA is the commit a review-fix task was minted against (the
	// finding's cited commit, falling back to the reviewed run's commit).
	// Structured so the claim-time done-preflight can run the
	// rejected-SHA disposition (exists? superseded? anchor gone?) without
	// parsing prompt prose. Empty on non-fix tasks.
	RejectedSHA string `json:"rejected_sha,omitempty"`
	// Anchor is the verbatim text a review-fix finding attaches to (same
	// provenance as RejectedSHA): the disposition's no-anchor-left signal.
	// Empty when the finding carried no anchor.
	Anchor string `json:"anchor,omitempty"`
}

type AgentResult struct {

	// VerifyTail is the last lines of the verify command's output: the
	// proof the task completed on.
	VerifyTail string `json:"verify_tail,omitempty"`
	// Commits are the commits whose `Task-Queue-ID: <id>` footer names this
	// task, DERIVED from git after the run (oldest first) — the agent never
	// reports them. FilesChanged is the union of files those commits
	// touched; CommitSHA is the newest one (the review sweeper and web UI
	// read both). A legacy `TQ_RESULT` self-report still fills them when
	// derivation finds nothing (in-flight tasks minted before derivation).
	Commits      []Commit `json:"commits,omitempty"`
	FilesChanged []string `json:"files_changed,omitempty"`
	CommitSHA    string   `json:"commit_sha,omitempty"`
	// PreflightDone carries the done-preflight reason when the worker
	// completed the task WITHOUT an agent run because the work was provably
	// already done (footer commits exist, item ticked, fix cured…). A
	// non-empty value means no session ran and no review may be minted for
	// this completion (review.enqueueReview skips it).
	PreflightDone string `json:"preflight_done,omitempty"`
	// contains filtered or unexported fields
}

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 Commit struct {
	SHA     string `json:"sha"`
	Subject string `json:"subject"`
}

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"`
	// contains filtered or unexported fields
}

type DLQFixVerdict string

type DepBump struct {
	Module  string `json:"module"`
	Version string `json:"version"`
}

type DepBumpExecutor struct {
	// ProjectsDir resolves relative Repo names in payloads ("demo" →
	// <ProjectsDir>/demo). Absolute Repo paths bypass it.
	ProjectsDir string
	// ExtraEnv is appended to every spawned go/git environment (e.g.
	// GOEXPERIMENT=jsonv2 — the pool unit env does not carry it).
	ExtraEnv []string
	// GoBin, GitBin, and TemplBin default to "go", "git", and "templ"
	// from PATH (templ absent is a soft skip; see regenerateTempl). The
	// overrides exist for tests and pinned deployments.
	GoBin    string
	GitBin   string
	TemplBin string
}

type DepBumpPayload struct {
	// Repo is the repository to bump: a name resolved against the
	// executor's ProjectsDir, or an absolute path. Required.
	Repo string `json:"repo"`
	// RepoName is the display name (task listings, logs).
	RepoName string `json:"repo_name,omitempty"`
	// Bumps are the exact pins to apply, in order. May be empty when the
	// task is release-only (the stale-build case: deps are already
	// committed, only the tag is missing).
	Bumps []DepBump `json:"bumps,omitempty"`
	// Release optionally tags (and pushes) after verification.
	Release *DepBumpRelease `json:"release,omitempty"`
	// V is the payload contract version. Zero decodes as v1; a version
	// above what this binary understands fails fast as a permanent error.
	V int `json:"v,omitempty"`
	// RequireClean refuses to start unless the repo's git tree is clean,
	// so the bump never interleaves with an agent's or human's WIP.
	// Default true.
	RequireClean *bool `json:"require_clean,omitempty"`
	// TimeoutMinutes caps each go command. Default 10; the worker's task
	// timeout still applies as the hard ceiling above it.
	TimeoutMinutes int `json:"timeout_minutes,omitempty"`
}

type DepBumpRelease struct {
	Version string `json:"version"`
	Push    bool   `json:"push,omitempty"`
}

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

type FailureClass string

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
	// VerifyStage names the failing stage OF THE VERIFY GATE on Stage
	// "verify" deaths: a VerifyStageGofmt / VerifyStageTest /
	// VerifyStageE2ETimeout / VerifyStageRun class. Stamped from the FULL
	// run output at the tail cut (verifyDeathStage), so the class stays
	// queryable after the evidence tail truncates and the sidecar logs
	// rotate. Empty for non-verify failures.
	VerifyStage string `json:"verify_stage,omitempty"`
	// Class is the retry taxonomy (FailureClass) stamped by the WORKER
	// after the run: only the worker sees the final error wrapper chain
	// (a verify gate wraps a plain failure and changes its class). Empty
	// on legacy facts; readers treat empty as "unclassified".
	Class string `json:"class,omitempty"`
}

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

type GitLogScanner struct {
	// Bin is the git binary; empty means "git" from PATH.
	Bin string
}

type GitScanner interface {
	CommitsByTrailer(ctx context.Context, repo, key, value string) ([]Commit, error)
}

type GitScannerFunc func(ctx context.Context, repo, key, value string) ([]Commit, 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"`
	// contains filtered or unexported fields
}

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 QuestionPendingError struct {
	Cause error
	// RetryAfter is how long to wait before the next attempt: until the
	// question expires. Always positive.
	RetryAfter time.Duration
	// ResumeCloseout marks a question asked during the CLOSE-OUT turn: the
	// work turn finished and its session is alive, so the re-claim resumes
	// at closeout instead of re-running the paid work turn.
	ResumeCloseout bool
}

type RateLimitError struct {
	Cause error
	// RetryAfter is how long to wait before the next attempt. Always
	// positive; capped by maxRateLimitWait.
	RetryAfter time.Duration
	// Provider is the provider tag parsed from the failing output
	// (crush logs "provider=synthetic"), empty when the output carries
	// none. Observability only: the worker's requeue log surfaces it so
	// operators can see WHICH provider armed the gate (16-00 f35).
	Provider string
	// ResumeCloseout marks a rate-limited CLOSE-OUT turn: the work turn
	// finished and its session is alive, so the re-claim resumes at
	// closeout instead of re-running the paid work turn. The worker
	// mirrors the flag into the requeue fact's evidence (16-00 f31).
	ResumeCloseout bool
}

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"`
	// CommitSHA is the commit the finding is anchored to (what the reviewer
	// inspected). Empty in model output is backfilled from the review
	// payload's CommitSHA at parse time — every request_changes finding
	// ends up anchored to a commit even when the model omits it.
	CommitSHA string `json:"commit_sha,omitempty"`
	// Anchor is the short VERBATIM text the finding is attached to (a line
	// or hunk of the cited file AS IT READS at the anchored commit). A bare
	// line-range citation ("lines 12-18", "x.go:3") is rejected at parse
	// time: line numbers go stale on the first rebase, and a fix agent that
	// must re-derive the location is re-doing the review (the 2026-09-10
	// 05-58 stale-anchor incident cost a rework day).
	Anchor string `json:"anchor,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"`
	// contains filtered or unexported fields
}

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"`
	// Report is the repo-relative path of the task's closeout report
	// (docs/status/tasks/<ts>_task-<id>.md; legacy root paths resolvable
	// too), resolved by the sweeper when it could find one — the done
	// prompt reads it directly instead of re-deriving it from the task
	// id. Empty when none was found.
	Report string `json:"report,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"`
	// contains filtered or unexported fields
}

type VerifyGateClass string

type VerifyGateError struct {
	Class  VerifyGateClass
	Verify string
	Cause  error
	Tail   string
}