harvest

type Config struct {
	// ProjectsDir is scanned (depth 1) for repos containing TodoFile.
	ProjectsDir string
	// DiscoveryAddr points at a project-discovery-daemon endpoint (unix
	// socket path, unix:// prefixed, or host:port) used INSTEAD of the
	// depth-1 ProjectsDir scan to enumerate candidate repos. Additive by
	// contract: an unreachable daemon logs one warning per tick and the
	// scan takes over. Empty keeps the zero-external-services default.
	DiscoveryAddr string
	// Log receives the daemon-discovery degradation warning; nil discards.
	Log *slog.Logger
	// Repos lists explicit repo directories; when set, ProjectsDir is ignored.
	Repos []string
	// Type is the task type enqueued (must match a registered executor).
	Type string
	// TodoFile is the backlog file name inside each repo.
	TodoFile string
	// MaxPerTick caps new enqueues per run across all repos.
	MaxPerTick int
	// MaxAttempts is the attempt budget for harvested tasks (0 = default).
	MaxAttempts int
	// Priority for harvested tasks.
	Priority int
	// SameSessionPriority promotes items whose text references /tmp paths
	// to this priority at enqueue time ("hot": work the same session, the
	// files will not survive). Zero disables the promotion.
	SameSessionPriority int
	// UseImportance resolves harvested priorities from the repo's
	// .config/metadata.yaml importance (default 50) plus keyword bumps,
	// clamped to the backlog band (ADR-0015 §3). Markers and hot promotion
	// apply regardless of this flag; a malformed metadata file skips the
	// repo's items with a reason instead of guessing.
	UseImportance bool
	// MaxPendingPerRepo caps how many PENDING tasks one repo may hold in
	// the queue (0 = unlimited): the queue is the WORKING SET, TODO_LIST.md
	// is the warehouse — prompts stay fresh and AI cost stays O(working
	// set). Admission resumes as claims drain the slot; running tasks do
	// not count (the repo-busy rule owns those).
	MaxPendingPerRepo int
	// PromptTemplate overrides DefaultPromptTemplate.
	PromptTemplate string
	// BatchPromptTemplate overrides DefaultBatchPromptTemplate (used only
	// when BatchItems > 1).
	BatchPromptTemplate string
	// BatchItems groups up to this many ADJACENT open items from the same
	// TODO_LIST.md section into ONE agent task (one session works the run
	// in order): fewer cold sessions, more done per provider window.
	// 0/1 = off (one item per task). The pool CLI default is 3 since
	// 2026-10-11 (docs/problems/major-prompting-and-batching.md). A batch
	// is ONE task against every gate (--max-per-tick, daily budget, repo
	// pacing) — the per-item cost is amortized, so raise the gates
	// consciously.
	BatchItems int
	// Model overrides the crush model ("provider/model") in every harvested
	// agent payload. Empty = the agent binary's default model.
	Model string
	// RepoIntervals sets a minimum gap between new enqueues per repo (by
	// repo name): after any enqueue for a repo, further items wait until
	// the interval has passed. Empty or zero entries = only the default
	// one-per-tick pacing applies.
	RepoIntervals map[string]time.Duration
	// RepoTimeouts sets a per-repo agent-task timeout ladder (by repo
	// name), pinned into each harvested payload's TimeoutMinutes: big
	// repos get long ceilings, quick ones stay tight. Repos without an
	// entry keep the executor's 30-minute default.
	RepoTimeouts map[string]time.Duration
	// DLQBackoff pauses harvesting of a repo whose recent work all went to
	// the dead-letter queue (dead tasks present, none completed, newest
	// dead within the window): the repo is poisoned until a human fixes or
	// rescues it. Zero disables the guard. Default 0 (set it, e.g. 30m).
	DLQBackoff time.Duration
	// RequireClean passes the clean-tree policy through to agent payloads:
	// nil = executor default (require a clean git tree), false lets agents
	// run on dirty repos (scratch/fixtures only), true forces the check.
	RequireClean *bool
	// DryRun reports what a real run would enqueue, without writing to the
	// queue. Result.Enqueued entries then carry an empty TaskID.
	DryRun bool
	// ForceRedispatch disables the mint-time done-check (the O4 escape
	// hatch): candidates whose work repo signals prove already landed are
	// minted anyway — a forced window is then expected to produce the stop
	// artifact (re-verify annotation + footer commit), not redo work.
	ForceRedispatch bool
}

type Drift struct {
	Kind       DriftKind
	Item       Item
	TaskID     task.ID
	TaskStatus task.Status
}

type DriftKind string

type DriftResult struct {
	Repos int
	// StaleOpen lists completed-work-open-checkbox drift; with DryRun unset,
	// each entry here also got a catch-up task enqueued (see Enqueued).
	StaleOpen []Drift
	// StaleDone lists ticked-checkbox-unfinished-task drift (report-only).
	StaleDone []Drift
	// Enqueued lists the catch-up tasks actually created this pass.
	Enqueued []Enqueued
	// ScanFailures lists repos that could not be read during the audit;
	// the audit keeps going past them.
	ScanFailures []ScanFailure
}

type Enqueued struct {
	Item   Item
	TaskID task.ID
	Fresh  bool // true when this run actually created the task
	Hot    bool // text referenced /tmp: enqueued at SameSessionPriority
}

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

type Item struct {
	Repo     string // absolute repo path
	RepoName string // project name (repo dir base name)
	Heading  string // nearest markdown heading above the item
	Text     string // the checkbox text, trimmed, priority marker stripped
	Key      string // stable dedup key: hash of repo name + MARKER-STRIPPED text
	Done     bool   // true when the checkbox is ticked ([x])
	// MarkerLevel is the parsed trailing `— P[1-4]` marker (1–4); 0 = none.
	// Stripped from Text before hashing so editing a marker never forks a
	// task (ADR-0015 §2). omitempty keeps legacy JSON consumers and golden
	// fixtures byte-stable for unmarked items.
	MarkerLevel int `json:"markerLevel,omitempty"`
}

type PayloadItem struct {
	// Repo is the payload's AgentPayload.Repo — the resolution-ready
	// reference the agent executor itself uses.
	Repo string
	// Text is the marker-stripped item text.
	Text string
	// Key is the item's dedup key (ItemKey derivation) — the score-cache
	// key.
	Key string
	// MarkerLevel is 0 (no marker) or 1-4 when the item carried a
	// `— P[1-4]` marker at harvest time.
	MarkerLevel int
}

type PriorityScorer interface {
	PriorityScore(ctx context.Context, itemKey string) (queue.PriorityScore, bool, error)
}

type PrioritySource string

type Provenance struct {
	Current     int
	Band        string
	ItemKey     string
	MarkerLevel int
	Score       *queue.PriorityScore
	History     []ProvenanceEvent
}

type ProvenanceEvent struct {
	At     time.Time
	Old    int
	New    int
	Source string
	Reason string
}

type PruneResult struct {
	Repos int
	// Cancelled lists pending tasks withdrawn because their TODO_LIST item
	// is now ticked — the zombies a pool relaunch would otherwise execute —
	// or because the item text is gone from the file entirely.
	Cancelled []PrunedTask
	// Running lists stale-item tasks currently executing: a cooperative
	// stop is an operator decision (tq cancel), not a sweep default.
	Running []PrunedTask
	// Dead lists stale-item tasks already dead-lettered: terminal, listed
	// because the dedup key still suppresses re-enqueue if the item is
	// ever un-ticked with unchanged text.
	Dead []PrunedTask
	// ScanFailures lists repos that could not be read; the prune keeps
	// going past them (same contract as Audit).
	ScanFailures []ScanFailure
}

type PruneWhy string

type PrunedTask struct {
	Item   Item
	TaskID task.ID
	Why    PruneWhy
}

type RedispatchFinding struct {
	Repo     string
	TaskID   task.ID
	Status   task.Status
	Attempts int
	ItemKey  string
	ItemText string
	Class    string
}

type RedispatchRefusalError struct {
	Reason string
}

type RedispatchResult struct {
	Repos        int
	Findings     []RedispatchFinding
	ScanFailures []ScanFailure
}

type RepriChange struct {
	TaskID      task.ID        `json:"task_id"`
	ItemText    string         `json:"item_text"`
	OldPriority int            `json:"old_priority"`
	NewPriority int            `json:"new_priority"`
	Source      PrioritySource `json:"source"`
}

type ResolveInput struct {
	Text              string
	MarkerLevel       int
	HotPriority       int  // --same-session-priority; <= 0 disables hot
	FlatPriority      int  // --priority fallback when nothing else applies
	Importance        int  // repo importance, already defaulted to 50
	ImportanceEnabled bool // importance + keyword composite on
	AIScore           *int // cached AI score; nil = no verdict yet
}

type Result struct {
	Repos    int
	Items    int
	Enqueued []Enqueued
	Skipped  []Skipped
}

type ScanFailure struct {
	Repo   string
	Reason string
}

type Skipped struct {
	Item   Item
	Reason string
}

type WatchConfig struct {
	// Addr is the daemon endpoint, same forms as Config.DiscoveryAddr
	// (unix socket path, unix:// prefixed, or host:port).
	Addr string
	// ProjectsDir scopes triggers to repos under this directory; events for
	// projects elsewhere on the daemon never fire a tick. Ignored when
	// Repos is set.
	ProjectsDir string
	// Repos, when set, restricts triggers to exactly these repos (the
	// pool's --repos mode) and overrides the ProjectsDir scope.
	Repos []string
	// RepoIntervals debounces triggers per repo, keyed by repo dir base
	// name (the same key the Harvester paces enqueues by): after a trigger
	// for a repo, further watch events for it wait out the repo's gap.
	// Repos without an entry have no explicit gap — the coalescing trigger
	// channel and the harvester's own pacing still apply.
	RepoIntervals map[string]time.Duration
	// Log receives connection and drop warnings; nil discards.
	Log *slog.Logger
	// InitialBackoff is the first reconnect delay after a dropped stream;
	// it doubles up to MaxBackoff. Zero uses the default (500ms).
	InitialBackoff time.Duration
	// MaxBackoff caps the reconnect backoff ladder. Zero uses the default
	// (30s).
	MaxBackoff time.Duration
}

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