pm

type AgentRole string

type Annotation struct {
	Timestamp time.Time `json:"timestamp"`
	Author    string    `json:"author"` // "user" or "ai"
	Text      string    `json:"text"`
}

type BackgroundState string

type BackgroundWork struct {
	// State is "waiting" while cloop is blocked on the work, "drained" once it
	// finished, and "abandoned" when it outlived its budget.
	State BackgroundState `json:"state"`
	// Detected is how many processes were still running.
	Detected int `json:"detected"`
	// Commands names them, for diagnosis.
	Commands []string `json:"commands,omitempty"`
	// WaitedSeconds is how long cloop blocked on the work.
	WaitedSeconds int `json:"waited_seconds,omitempty"`
	// Terminated is how many processes were killed after outliving the budget.
	Terminated int `json:"terminated,omitempty"`
	// DetectedAt is when the work was first seen.
	DetectedAt time.Time `json:"detected_at"`
}

type BranchActivation struct {
	TaskID    int
	Title     string
	Activated bool   // true = task kept/reset to pending; false = task skipped
	Branch    string // "on_success" or "on_failure"
}

type FieldChange struct {
	Field    string
	OldValue string
	NewValue string
}

type Link struct {
	URL   string   `json:"url"`
	Label string   `json:"label,omitempty"`
	Kind  LinkKind `json:"kind"`
}

type LinkKind string

type MergeOptions struct {
	// Provider options forwarded to the AI call.
	Provider provider.Options
}

type MoveResult struct {
	// Task is the task as it now exists in the destination plan (new ID).
	Task *Task
	// SrcTaskID is the original ID in the source plan.
	SrcTaskID int
	// DstTaskID is the newly assigned ID in the destination plan.
	DstTaskID int
}

type OverdueResult struct {
	Task    *Task
	Overdue bool
	// OldPriority is the priority before boosting (0 if not boosted).
	OldPriority int
	// Boosted is true when the priority was changed.
	Boosted bool
}

type Plan struct {
	Goal    string  `json:"goal"`
	Tasks   []*Task `json:"tasks"`
	Version int     `json:"version"`
}

type PlanDiff struct {
	Added   []*Task
	Removed []*Task
	Changed []TaskDiff
}

type ProjectContext struct {
	FileTree  string
	GitStatus string
	RecentLog string
	WorkDir   string
}

type PruneStats struct {
	// Deleted counts snapshot files removed (or, for a dry run, that would
	// have been removed).
	Deleted int
	// BytesFreed sums their sizes.
	BytesFreed int64
	// Remaining counts the snapshots left behind.
	Remaining int
}

type SLAStats struct {
	// Total number of tasks that had a deadline.
	Total int
	// Met is the number of tasks completed (done/skipped) before or by their deadline.
	Met int
	// Missed is the number of tasks that failed or are overdue past their deadline.
	Missed int
	// ComplianceRatio is Met/Total (NaN when Total==0).
	ComplianceRatio float64
}

type Snapshot struct {
	Version   int       `json:"version"`
	Timestamp time.Time `json:"timestamp"`
	Plan      *Plan     `json:"plan"`
}

type SnapshotMeta struct {
	Version   int       `json:"version"`
	Timestamp time.Time `json:"timestamp"`
	Filename  string    `json:"filename"`
	TaskCount int       `json:"task_count"`
	Summary   string    `json:"summary"`
}

type Task struct {
	ID               int          `json:"id"`
	Title            string       `json:"title"`
	Description      string       `json:"description"`
	Priority         int          `json:"priority"` // 1 = highest
	Status           TaskStatus   `json:"status"`
	Role             AgentRole    `json:"role,omitempty"`       // specialized agent role for this task
	DependsOn        []int        `json:"depends_on,omitempty"` // IDs of tasks that must complete before this one
	Result           string       `json:"result,omitempty"`
	StartedAt        *time.Time   `json:"started_at,omitempty"`
	CompletedAt      *time.Time   `json:"completed_at,omitempty"`
	Deadline         *time.Time   `json:"deadline,omitempty"`          // optional SLA deadline; overdue tasks are auto-boosted to P1
	VerifyRetries    int          `json:"verify_retries,omitempty"`    // number of times task was re-queued by verifier
	GitHubIssue      int          `json:"github_issue,omitempty"`      // linked GitHub issue number (0 = none)
	EstimatedMinutes int          `json:"estimated_minutes,omitempty"` // AI-predicted duration
	ActualMinutes    int          `json:"actual_minutes,omitempty"`    // measured duration (set on completion)
	ArtifactPath     string       `json:"artifact_path,omitempty"`     // path to the full AI response artifact file
	FailureDiagnosis string       `json:"failure_diagnosis,omitempty"` // AI diagnosis of what went wrong on failure
	Tags             []string     `json:"tags,omitempty"`              // user-defined labels for filtering
	FailCount        int          `json:"fail_count,omitempty"`        // number of times this task has been marked failed
	HealAttempts     int          `json:"heal_attempts,omitempty"`     // number of auto-heal re-attempts made for this task
	Annotations      []Annotation `json:"annotations,omitempty"`       // timestamped notes from user or AI
	Condition        string       `json:"condition,omitempty"`         // optional gate: "$cmd" = shell check, else AI yes/no prompt
	Recurrence       string       `json:"recurrence,omitempty"`        // cron expression (5-field); auto-resets task when due
	NextRunAt        *time.Time   `json:"next_run_at,omitempty"`       // computed next trigger time for recurring tasks
	RequiresApproval bool         `json:"requires_approval,omitempty"` // task must be interactively approved before execution
	Approved         bool         `json:"approved,omitempty"`          // pre-approved via 'cloop task approve'; bypasses interactive gate
	MaxMinutes       int          `json:"max_minutes,omitempty"`       // per-task execution time budget in minutes (0 = no limit)
	Assignee         string       `json:"assignee,omitempty"`          // team member assigned to this task
	ExternalURL      string       `json:"external_url,omitempty"`      // URL of the external resource (e.g. GitHub PR)
	Links            []Link       `json:"links,omitempty"`             // external URLs/tickets/docs associated with this task
	Pinned           bool         `json:"pinned,omitempty"`            // pinned tasks always appear at the top of task lists
	TDDStatus        string       `json:"tdd_status,omitempty"`        // TDD verification outcome: "pass", "fail", or "skipped"
	TDDScore         int          `json:"tdd_score,omitempty"`         // TDD score 0-100 (percentage of acceptance criteria met)
	SprintID         int          `json:"sprint_id,omitempty"`         // sprint this task belongs to (0 = unassigned)
	ComplexitySize   string       `json:"complexity_size,omitempty"`   // T-shirt size: XS/S/M/L/XL (set by ai-complexity)
	StoryPoints      int          `json:"story_points,omitempty"`      // Fibonacci story points: 1/2/3/5/8/13 (set by ai-complexity)
	// ChainInput holds the previous task's output when this task is part of a pipeline
	// chain (tagged "chain:<uuid>"). It is runtime-only and never persisted.
	ChainInput string `json:"-"`
	// OnSuccess lists task IDs to activate (keep pending) when this task succeeds.
	// Tasks in OnFailure are skipped when the success branch is taken.
	OnSuccess []string `json:"on_success,omitempty"`
	// OnFailure lists task IDs to activate (keep pending) when this task fails.
	// Tasks in OnSuccess are skipped when the failure branch is taken.
	OnFailure []string `json:"on_failure,omitempty"`
	// RiskScore is the cached AI likelihood/risk score 1-10 (set by ai-risk-matrix).
	RiskScore int `json:"risk_score,omitempty"`
	// ImpactScore is the cached AI strategic impact score 1-10 (set by ai-risk-matrix or ai-impact).
	ImpactScore int `json:"impact_score,omitempty"`
	// RetryBudget caps the total number of provider attempts this task is
	// allowed to consume across all DoWithRetry calls (Task 20114). Zero
	// or unset means use provider.DefaultRetryBudget. Tasks known to be
	// expensive or experimental can set a tighter cap to bound the blast
	// radius of repeated provider failures.
	RetryBudget int `json:"retry_budget,omitempty"`
	// WriteBackBranch and WriteBackCommit record where an isolated executor
	// left this task's work (Task 20180). They are set only for a task that
	// ran somewhere the hub does not share a filesystem with: a local run's
	// changes are already in the working tree, so there is no branch to name
	// and nothing to point a reviewer at. When they are empty, the result was
	// produced in place; when they are set, the work is only reachable by
	// fetching the named branch.
	WriteBackBranch string `json:"write_back_branch,omitempty"`
	WriteBackCommit string `json:"write_back_commit,omitempty"`
	// ExecutorID, ExecutorKind and Isolation record *where* this task ran
	// (Task 20244). The hub's headline claim is that it never spawns a
	// harness on the host; without these the claim is unauditable after the
	// fact, because executor identity otherwise exists only in the
	// project_executors binding — which says where the project's *next* task
	// would go, not where this one went — and in audit payloads that are
	// scoped to a dispatch rather than to a task.
	//
	// They are stamped at task start, not at completion, so a task that is
	// still in flight is attributable too: "what is running on that edge
	// device right now" is the question an operator asks during an incident,
	// and a field that only appears at completion cannot answer it.
	//
	// Isolation is the boundary strength the executor advertised
	// ("none" | "container" | "vm" | "remote"), mirroring
	// executor.Capabilities.Isolation. Kind mirrors executor.Kind()
	// ("localprocess" | "container" | "remote" | "kubernetes"). Held as
	// strings rather than the executor package's named types to keep pm free
	// of a dependency on the execution layer — pm is the data model that the
	// CLI, the TUI and the exporters all load, and none of them place work.
	//
	// Isolation "none" or kind "localprocess" means the harness ran as a
	// child process of the hub with the host's filesystem and network. That
	// is the case the UI renders differently on purpose: it is legitimate for
	// a developer's own machine and is precisely what must never happen
	// silently on a shared hub.
	ExecutorID   string `json:"executor_id,omitempty"`
	ExecutorKind string `json:"executor_kind,omitempty"`
	Isolation    string `json:"isolation,omitempty"`
	// RunID names the execution this task was dispatched into (Task 20282).
	//
	// It is the join key between this task's audit rows and the secret-lease
	// rows the hub wrote when it started the run — "which leases did task 63
	// hold" has as many answers as task 63 has attempts, and only a per-run
	// token makes the question answerable exactly.
	//
	// Stamped at start alongside the executor fields, and deliberately *not*
	// cleared when a task is reset: the run id belongs to the attempt that is
	// ending, and the terminal audit row is written after the reset. It is
	// overwritten by the next attempt's dispatch.
	RunID string `json:"run_id,omitempty"`
	// Background records work the agent harness left running after it claimed
	// to be finished (Task 20205), so the UI can show why a task waited, or
	// why it was not accepted as done.
	Background *BackgroundWork `json:"background,omitempty"`
	// Abort records that this task's stored summary is a provider or harness
	// refusal rather than work (Task 20224). It is set by the orchestrator's
	// pre-completion sweep and is what stops a plan full of usage-limit
	// messages counting as finished. See abort.go for the lifecycle.
	Abort *TaskAbort `json:"abort,omitempty"`
}

type TaskAbort struct {
	// Class is the orchestrator's AbortClass as a string ("usage_limit",
	// "quota_exceeded", "harness_refused", ...). It is kept as a plain string
	// because the classifier lives in pkg/orchestrator, which imports this
	// package; holding the typed value here would invert that dependency.
	Class string `json:"class"`
	// Reason is operator-facing prose naming what the provider said.
	Reason string `json:"reason"`
	// Evidence is the matched excerpt of the stored summary, so the record
	// shows what was actually seen rather than our paraphrase of it.
	Evidence string `json:"evidence,omitempty"`
	// DetectedAt is when the sweep first recognised this outcome.
	DetectedAt time.Time `json:"detected_at,omitempty"`
	// SummaryFingerprint binds this record to the exact summary it describes.
	// When the task runs again its summary changes, the fingerprint stops
	// matching, and the whole record — including any clearance below — ceases
	// to apply. It is what makes reusing the stored classification safe rather
	// than merely cheap: a stale verdict can never mask a fresh refusal.
	//
	// Not a credential despite being a hash: it digests the task's own summary,
	// which is already visible to anyone who can read the task, and it gates a
	// cache decision rather than access to anything.
	SummaryFingerprint string `json:"summary_fingerprint,omitempty"`

	// Cleared records a verdict that the work exists despite the refusal
	// summary — typically because a later task re-landed it. A cleared abort
	// stops blocking plan completion but stays visible, because the ledger
	// entry is still wrong and a reader of project history deserves to know
	// why it was allowed to stand.
	Cleared bool `json:"cleared,omitempty"`
	// ClearedBy names who made that call ("cli", "triage", a username).
	ClearedBy string `json:"cleared_by,omitempty"`
	// ClearedNote is the evidence for the clearance. Required in practice:
	// a clearance without a reason is indistinguishable from giving up.
	ClearedNote string     `json:"cleared_note,omitempty"`
	ClearedAt   *time.Time `json:"cleared_at,omitempty"`
}

type TaskDiff struct {
	ID      int
	Title   string
	Changes []FieldChange
}

type TaskStatus string