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 open items from the same
	// TODO_LIST.md section into ONE agent task (one session works them
	// in order): fewer cold sessions, more done per provider window.
	// Grouping is SECTION-scoped, not adjacency-scoped: a done, blocked
	// or already-known item between fresh ones does not fork the batch
	// (the section-goal form of
	// docs/problems/major-prompting-and-batching.md, 2026-11-03).
	// 0/1 = off (one item per task). The pool CLI default is 5 since
	// 2026-11-03 (3 from 2026-10-11). 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
	// BatchEffortMinutes caps the SUMMED per-item effort estimates of
	// one batched run (effort-aware batching, 2026-11-03): a 3-hour item
	// ships alone while ten 10-minute items ride together, all under
	// the same context cap. 0 = BatchItems x DefaultBatchTimeoutMinutes,
	// which under flat estimates is exactly the count cap (zero behavior
	// change without an estimator). Estimates are SCHEDULING SIGNALS
	// (ADR-0015 §signals): they size runs and raise payload timeouts,
	// never lower them, and never touch trust or priority.
	BatchEffortMinutes int
	// EffortEstimator, when set, predicts per-item work minutes (keyed
	// by Item.Key) for run sizing and timeout budgets. nil keeps the
	// flat per-item default (count-equivalent grouping). Called once per
	// repo with the admissible candidates; a missing key or non-positive
	// value falls back to the flat default, so a failed estimation can
	// never drop or stall work.
	EffortEstimator EffortEstimator
	// 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
	// RedispatchCooldown is the window a live repo-side claim marker
	// (.tq/claimed/<id>, tq-claim.sh) machine-blocks re-dispatch of the
	// same work at mint time (owner ruling fam.12.3, 2026-10-17): a
	// marker younger than the window means another dispatched session
	// holds the item. Zero = 6h (the tq-claim.sh TQ_STALE_AFTER default);
	// the claim sweep releasing stale/footer-committed markers is what
	// ends the block, never this gate alone. The sibling verdict marker
	// (.tq/verdicts/<id>, already_done terminal state) blocks while
	// PRESENT regardless of this window — it expires only via the marker
	// TTL sweep (TQ_VERDICT_TTL). Both markers are read by the mint-time
	// RedispatchCheck; ForceRedispatch bypasses them with the rest of the
	// gate.
	RedispatchCooldown time.Duration
}

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 EffortCache struct {
	// contains filtered or unexported fields
}

type EffortEntry struct {
	Minutes    int       `json:"minutes"`
	Source     string    `json:"source"` // "jev:<model>"
	Confidence float64   `json:"confidence"`
	At         time.Time `json:"at"`
}

type EffortEstimator interface {
	// EstimateEffort returns predicted minutes keyed by Item.Key.
	// Missing keys and non-positive values use the flat default.
	EstimateEffort(ctx context.Context, items []Item) map[string]int
}

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 JevConfig struct {
	// APIKey is the TypeSafe bearer token (required — a missing key at
	// startup is a configuration error, not a runtime fallback).
	APIKey string
	// Model overrides DefaultModel.
	Model string
	// BaseURL overrides DefaultBaseURL (tests point it at httptest).
	BaseURL string
	// Timeout bounds one request; 0 = DefaultTimeout.
	Timeout time.Duration
	// CachePath persists estimates as a JSON sidecar; empty disables
	// persistence (every pass re-estimates).
	CachePath string
	// Log receives one WARN line per degraded pass; nil discards.
	Log *slog.Logger
}

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

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
}