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
	// PromptTemplate overrides DefaultPromptTemplate.
	PromptTemplate string
	// 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
}

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
}

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
	Key      string // stable dedup key: hash of repo name + item text
	Done     bool   // true when the checkbox is ticked ([x])
}

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 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
}

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