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 CommitPolicy struct {
	// Enabled turns the check on. Pushed is kept while it is off, so switching
	// it off and on again does not lose the choice.
	Enabled bool `json:"enabled"`
	// Pushed also requires the commits a task made to be on the upstream of
	// the branch they are on.
	Pushed bool `json:"pushed,omitempty"`
}

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 NodeLoss struct {
	// ExecutorID is the executor that went unreachable.
	ExecutorID string `json:"executor_id"`
	// LostAt is when it was found unreachable.
	LostAt time.Time `json:"lost_at"`
	// SessionID is the executor session that was lost with it.
	SessionID string `json:"session_id,omitempty"`
	// Attempt is that session's attempt number: 1 for the original dispatch.
	Attempt int `json:"attempt,omitempty"`
}

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 ReviewFinding struct {
	// Severity is "blocker", "major", "minor" or "nit".
	Severity string `json:"severity"`
	File     string `json:"file,omitempty"`
	Line     int    `json:"line,omitempty"`
	Title    string `json:"title"`
	Detail   string `json:"detail,omitempty"`
}

type ReviewGate struct {
	// Enabled turns the gate on. Everything else is kept while it is off, so
	// switching it off and on again does not lose the reviewer's settings.
	Enabled bool `json:"enabled"`
	// Provider is the reviewer's provider; empty means the project's own.
	Provider string `json:"provider,omitempty"`
	// Model is the reviewer's model; empty means that provider's default —
	// or, when Provider is empty too, the model the project works with.
	Model string `json:"model,omitempty"`
	// Effort is the reviewer's reasoning effort (claudecode only).
	Effort string `json:"effort,omitempty"`
	// Mode is what a review that does not approve does: ReviewModeFix
	// (the default when empty), ReviewModeBlock or ReviewModeAdvisory.
	Mode string `json:"mode,omitempty"`
	// MaxFixRounds bounds how often ReviewModeFix sends a task back.
	// 0 means DefaultReviewFixRounds.
	MaxFixRounds int `json:"max_fix_rounds,omitempty"`
	// Instructions are extra review criteria from the operator, appended to
	// every review ("reject anything that touches the migrations").
	Instructions string `json:"instructions,omitempty"`
}

type ReviewPublish struct {
	Repo    string `json:"repo"`
	Remote  string `json:"remote"`
	Ref     string `json:"ref"`
	Commit  string `json:"commit,omitempty"`
	Outcome string `json:"outcome"`
	Detail  string `json:"detail,omitempty"`
}

type ReviewVerdict string

type ReviewedRepo struct {
	// Path is the repository's directory relative to the project ("." for
	// the project's own repository).
	Path string `json:"path"`
	// Base and Head are the commits the diff was taken between; the working
	// tree's uncommitted changes were included on top of Head.
	Base string `json:"base,omitempty"`
	Head string `json:"head,omitempty"`
	// Files, Insertions and Deletions summarise the diff.
	Files      int `json:"files"`
	Insertions int `json:"insertions,omitempty"`
	Deletions  int `json:"deletions,omitempty"`
	// Commits is how many commits Base..Head holds.
	Commits int `json:"commits,omitempty"`
	// Uncommitted reports that the working tree held changes not in Head.
	Uncommitted bool `json:"uncommitted,omitempty"`
	// Truncated reports that the diff was cut to fit the review prompt.
	Truncated bool `json:"truncated,omitempty"`
}

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: it is a
	// copy of up to 16 MiB of transcript, so the orchestrator derives it again from
	// the stored predecessor when it dispatches the task (ensureChainInput) rather
	// than writing it into every save.
	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"`
	// Review records what the project's review gate decided about this task's
	// changes, and which of the pushes it held were published (Task 20357).
	// Nil when the gate was off. See review.go.
	Review *TaskReview `json:"review,omitempty"`
	// Quarantine marks a task the control plane suspects of taking down the
	// nodes that ran it (Task 20391): two or more distinct executors went
	// unreachable while it was running. It runs again only after an explicit
	// reset. See quarantine.go.
	//
	// Not a plan_tasks column: it lives in task_quarantine, written by the
	// failover that marks it and deleted by the reset that clears it, and by
	// nothing else. A run's save holds a copy of the plan loaded before the
	// mark existed, and must be able to neither write it back nor away.
	Quarantine *TaskQuarantine `json:"quarantine,omitempty"`
	// Stop says why this task's execution was ended from outside its run, set
	// by whoever settles the run for the one save that records the end — the
	// hub, for a workload its executor stopped at its disk limit (Task 20405).
	// It is what that save's task.finish row carries as structured fields.
	//
	// Never persisted, and not a plan_tasks column: the durable account is the
	// note written beside it, which the task keeps; this exists only so the
	// terminal audit row can say "disk_limit" and both sizes as fields an
	// auditor can query, rather than as prose.
	Stop *TaskStop `json:"-"`
}

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 TaskQuarantine struct {
	// Kind is what the task is suspected of; QuarantineNodeKiller.
	Kind string `json:"kind"`
	// Reason is one sentence naming the nodes.
	Reason string `json:"reason,omitempty"`
	// Nodes are the losses behind the mark, oldest first.
	Nodes []NodeLoss `json:"nodes,omitempty"`
	// MarkedAt is when the task was marked.
	MarkedAt time.Time `json:"marked_at"`
	// MarkedBy is what marked it, e.g. "failover".
	MarkedBy string `json:"marked_by,omitempty"`
}

type TaskReview struct {
	// Verdict is the final outcome across every round.
	Verdict ReviewVerdict `json:"verdict"`
	// Mode is the gate's mode when the review ran.
	Mode string `json:"mode"`
	// Blocked reports that the gate stopped the task's changes from being
	// published: the verdict was not an approval and the mode was not
	// advisory.
	Blocked bool `json:"blocked,omitempty"`
	// Provider and Model name the reviewer.
	Provider string `json:"provider,omitempty"`
	Model    string `json:"model,omitempty"`
	// Rounds is how many reviews ran; FixRounds how often the agent was sent
	// back with findings.
	Rounds    int `json:"rounds"`
	FixRounds int `json:"fix_rounds,omitempty"`
	// Summary is the reviewer's one-paragraph assessment of the last round.
	Summary string `json:"summary,omitempty"`
	// Findings are the last round's findings, most severe first.
	Findings []ReviewFinding `json:"findings,omitempty"`
	// Error says why no verdict was reached (ReviewUnavailable).
	Error string `json:"error,omitempty"`
	// Repos describes what the last round reviewed, per repository.
	Repos []ReviewedRepo `json:"repos,omitempty"`
	// Published records each push the agent attempted while the gate held it,
	// and what became of it.
	Published []ReviewPublish `json:"published,omitempty"`
	// ReviewedAt is when the last round finished.
	ReviewedAt time.Time `json:"reviewed_at"`
}

type TaskStatus string

type TaskStop struct {
	// Cause is the machine-readable reason: StopDiskLimit.
	Cause string
	// Detail is the sentence naming it, with its numbers.
	Detail string
	// DiskUsedMB and DiskLimitMB are the measured workspace and the limit it
	// was held to, for a disk-limit stop.
	DiskUsedMB  int64
	DiskLimitMB int
}