projectautomation

type Automation struct {
	ID                    string   `json:"id"`
	ProjectID             string   `json:"project_id"`
	AutomationRef         string   `json:"automation_ref"`
	Title                 string   `json:"title"`
	Purpose               string   `json:"purpose"`
	Status                string   `json:"status"`
	AgentID               string   `json:"agent_id"`
	PlanID                string   `json:"plan_id,omitempty"`
	AllowedTaskRefs       []string `json:"allowed_task_refs,omitempty"`
	RequiredReviewTaskIDs []string `json:"required_review_task_ids,omitempty"`
	TriggerKind           string   `json:"trigger_kind"`
	SourceKind            string   `json:"source_kind,omitempty"`
	SchedulePolicy        string   `json:"schedule_policy,omitempty"`
	PermissionRef         string   `json:"permission_ref"`
	CreatedByRunID        string   `json:"created_by_run_id,omitempty"`
	TraceID               string   `json:"trace_id,omitempty"`
	// Harness/Model/Provider carry the per-agent harness selection from the
	// workflow definition through to the runner. Empty means inherit the
	// server/runner default (codex). Populated by the workflow compiler from
	// the [[agents]] block; read by claimedRunForAutomation to surface on the
	// ClaimedRun response so the runner can dispatch per-run.
	Harness   string    `json:"harness,omitempty"`
	Model     string    `json:"model,omitempty"`
	Provider  string    `json:"provider,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

type AutomationAgent struct {
	ID              string        `json:"id"`
	DisplayName     string        `json:"display_name"`
	Purpose         string        `json:"purpose"`
	Enabled         bool          `json:"enabled"`
	AllowedSkills   []string      `json:"allowed_skills,omitempty"`
	AllowedTools    []string      `json:"allowed_tools,omitempty"`
	AllowedCommands []CommandSpec `json:"allowed_commands,omitempty"`
	DeniedCommands  []string      `json:"denied_commands,omitempty"`
	WorkspaceMode   string        `json:"workspace_mode"`
	NetworkPolicy   string        `json:"network_policy"`
	SecretPolicy    string        `json:"secret_policy"`
	LogPolicy       string        `json:"log_policy"`
	MaxRuntime      time.Duration `json:"max_runtime"`
	MaxRetries      int           `json:"max_retries"`
}

type AutomationAttempt struct {
	ID                 string    `json:"id"`
	ProjectID          string    `json:"project_id"`
	AutomationRunID    string    `json:"automation_run_id"`
	AttemptNumber      int       `json:"attempt_number"`
	RunnerKind         string    `json:"runner_kind"`
	CommandRef         string    `json:"command_ref,omitempty"`
	InputSummaryHash   string    `json:"input_summary_hash,omitempty"`
	OutputSummaryHash  string    `json:"output_summary_hash,omitempty"`
	Status             string    `json:"status"`
	FailureCategory    string    `json:"failure_category,omitempty"`
	DurationMS         int64     `json:"duration_ms"`
	VerifierResultRefs []string  `json:"verifier_result_refs,omitempty"`
	EvidenceRefs       []string  `json:"evidence_refs,omitempty"`
	ClaimRefs          []string  `json:"claim_refs,omitempty"`
	KnowledgeRefs      []string  `json:"knowledge_candidate_refs,omitempty"`
	CreatedAt          time.Time `json:"created_at"`
	FinishedAt         time.Time `json:"finished_at,omitempty"`
}

type AutomationDeleteCounts struct {
	Automations int `json:"automations"`
	Runs        int `json:"runs"`
}

type AutomationFilter struct {
	ProjectID string `json:"project_id,omitempty"`
	Status    string `json:"status,omitempty"`
	AgentID   string `json:"agent_id,omitempty"`
	PlanID    string `json:"plan_id,omitempty"`
}

type AutomationParallelBatch struct {
	ID                string    `json:"id"`
	ProjectID         string    `json:"project_id"`
	AutomationRunID   string    `json:"automation_run_id"`
	OrchestratorRunID string    `json:"orchestrator_run_id"`
	PlanID            string    `json:"plan_id"`
	TaskIDs           []string  `json:"task_ids"`
	Status            string    `json:"status"`
	SafetyReason      string    `json:"safety_reason"`
	ConflictSummary   string    `json:"conflict_summary,omitempty"`
	CreatedAt         time.Time `json:"created_at"`
	UpdatedAt         time.Time `json:"updated_at"`
}

type AutomationRun struct {
	ID                string   `json:"id"`
	ProjectID         string   `json:"project_id"`
	AutomationID      string   `json:"automation_id"`
	AgentID           string   `json:"agent_id"`
	PlanID            string   `json:"plan_id"`
	TaskID            string   `json:"task_id"`
	WorkTaskStatus    string   `json:"work_task_status"`
	Status            string   `json:"status"`
	RunnerKind        string   `json:"runner_kind"`
	AgentRunID        string   `json:"agent_run_id,omitempty"`
	TraceID           string   `json:"trace_id,omitempty"`
	AttemptCount      int      `json:"attempt_count"`
	OrchestratorRunID string   `json:"orchestrator_run_id,omitempty"`
	ParentRunID       string   `json:"parent_run_id,omitempty"`
	WorkerRunIDs      []string `json:"worker_run_ids,omitempty"`
	ParallelGroupID   string   `json:"parallel_group_id,omitempty"`
	FailureCategory   string   `json:"failure_category,omitempty"`
	SafeSummary       string   `json:"safe_summary,omitempty"`
	// OperatorDiagnostics carries unsanitized failure detail (absolute paths, git
	// commands, refs) populated by the runner on failure. It is OPERATOR-ONLY: the
	// MCP boundary (mcp_adapter.go) projects it out of agent responses unless the
	// caller passes include_diagnostics=true. Agents never see it by default, so
	// the privacy boundary (no roots/paths/commands to agents) is preserved.
	OperatorDiagnostics string    `json:"operator_diagnostics,omitempty"`
	ClaimID             string    `json:"claim_id,omitempty"`
	RunnerID            string    `json:"runner_id,omitempty"`
	ClaimedAt           time.Time `json:"claimed_at,omitempty"`
	LastHeartbeatAt     time.Time `json:"last_heartbeat_at,omitempty"`
	LeaseExpiresAt      time.Time `json:"lease_expires_at,omitempty"`
	StartedAt           time.Time `json:"started_at,omitempty"`
	FinishedAt          time.Time `json:"finished_at,omitempty"`
	CreatedAt           time.Time `json:"created_at"`
	UpdatedAt           time.Time `json:"updated_at"`
}

type CancelRunInput struct {
	ProjectID       string   `json:"project_id,omitempty"`
	RunID           string   `json:"run_id"`
	FailureCategory string   `json:"failure_category,omitempty"`
	SafeSummary     string   `json:"safe_summary,omitempty"`
	EvidenceRefs    []string `json:"evidence_refs,omitempty"`
}

type ClaimNextRunInput struct {
	ProjectID  string `json:"project_id,omitempty"`
	AgentID    string `json:"agent_id,omitempty"`
	RunnerKind string `json:"runner_kind,omitempty"`
	RunnerID   string `json:"runner_id,omitempty"`
}

type ClaimedRun struct {
	Run        AutomationRun  `json:"run"`
	Automation *Automation    `json:"automation,omitempty"`
	CodexInput CodexTaskInput `json:"codex_input"`
	TimeoutMS  int64          `json:"timeout_ms"`
	// AgentHarness/AgentModel/AgentProvider carry the per-agent harness
	// selection from the workflow definition, resolved at claim time from the
	// automation row. Empty means the runner uses its startup default. The
	// runner reads these to dispatch the claimed run to the correct adapter
	// (codex or crush) with the right model/provider — Phase 3 per-agent
	// routing.
	AgentHarness  string `json:"agent_harness,omitempty"`
	AgentModel    string `json:"agent_model,omitempty"`
	AgentProvider string `json:"agent_provider,omitempty"`
}

type CodexCommand struct {
	Path      string
	Args      []string
	Env       []string
	StdinFile string
	Dir       string
	Timeout   time.Duration
}

type CodexCommandInput struct {
	BinaryPath string
	InputPath  string
	Timeout    time.Duration
	EnvAllow   map[string]string
}

type CodexRunResult struct {
	ExitCode            int
	Duration            time.Duration
	TimedOut            bool
	OutputTruncated     bool
	SafeFailureCategory string
	Output              string
}

type CodexTaskInput struct {
	SchemaVersion           int      `json:"schema_version"`
	ProjectID               string   `json:"project_id"`
	MCPServerURL            string   `json:"mcp_server_url,omitempty"`
	AutomationRunID         string   `json:"automation_run_id"`
	TraceID                 string   `json:"trace_id,omitempty"`
	PlanID                  string   `json:"plan_id"`
	TaskID                  string   `json:"task_id"`
	TaskRef                 string   `json:"task_ref"`
	Title                   string   `json:"title"`
	Description             string   `json:"description,omitempty"`
	EvidenceNeeded          []string `json:"evidence_needed,omitempty"`
	ContextPackRefs         []string `json:"context_pack_refs,omitempty"`
	WorkPlanContext         []string `json:"work_plan_context,omitempty"`
	DependencyContext       []string `json:"dependency_context,omitempty"`
	FilesToRead             []string `json:"files_to_read,omitempty"`
	LikelyFilesAffected     []string `json:"likely_files_affected,omitempty"`
	VerificationRequirement string   `json:"verification_requirement"`
	ExpectedOutput          string   `json:"expected_output,omitempty"`
	FailureCriteria         string   `json:"failure_criteria,omitempty"`
	ResumeInstructions      string   `json:"resume_instructions,omitempty"`
	AcceptanceCriteria      []string `json:"acceptance_criteria,omitempty"`
	StopConditions          []string `json:"stop_conditions,omitempty"`
	VerifierLadder          []string `json:"verifier_ladder,omitempty"`
	RegressionApplicability string   `json:"regression_test_applicability,omitempty"`
	DownstreamImpactRefs    []string `json:"downstream_impact_refs,omitempty"`
	OutputContract          string   `json:"output_contract,omitempty"`
	RunnerInstructions      []string `json:"runner_instructions"`
}

type CommandSpec struct {
	Command string   `json:"command"`
	Args    []string `json:"args,omitempty"`
}

type CompleteAttemptInput struct {
	ProjectID          string   `json:"project_id,omitempty"`
	RunID              string   `json:"run_id"`
	ClaimID            string   `json:"claim_id,omitempty"`
	RunnerID           string   `json:"runner_id,omitempty"`
	Status             string   `json:"status"`
	FailureCategory    string   `json:"failure_category,omitempty"`
	DurationMS         int64    `json:"duration_ms,omitempty"`
	VerifierResultRefs []string `json:"verifier_result_refs,omitempty"`
	EvidenceRefs       []string `json:"evidence_refs,omitempty"`
	ClaimRefs          []string `json:"claim_refs,omitempty"`
	ReviewRefs         []string `json:"review_result_refs,omitempty"`
	KnowledgeRefs      []string `json:"knowledge_candidate_refs,omitempty"`
}

type ComputeParallelBatchInput struct {
	ProjectID         string   `json:"project_id,omitempty"`
	AutomationRunID   string   `json:"automation_run_id,omitempty"`
	OrchestratorRunID string   `json:"orchestrator_run_id,omitempty"`
	PlanID            string   `json:"plan_id,omitempty"`
	TaskIDs           []string `json:"task_ids,omitempty"`
	MaxTasks          int      `json:"max_tasks,omitempty"`
}

type ConfidenceGovernance interface {
	RecordConfidenceRef(context.Context, GovernanceConfidenceInput) (string, error)
}

type CreateAutomationInput struct {
	ProjectID             string   `json:"project_id,omitempty"`
	AutomationRef         string   `json:"automation_ref"`
	Title                 string   `json:"title"`
	Purpose               string   `json:"purpose"`
	Status                string   `json:"status,omitempty"`
	AgentID               string   `json:"agent_id"`
	PlanID                string   `json:"plan_id,omitempty"`
	AllowedTaskRefs       []string `json:"allowed_task_refs,omitempty"`
	RequiredReviewTaskIDs []string `json:"required_review_task_ids,omitempty"`
	TriggerKind           string   `json:"trigger_kind,omitempty"`
	SchedulePolicy        string   `json:"schedule_policy,omitempty"`
	PermissionRef         string   `json:"permission_ref"`
	SourceKind            string   `json:"source_kind,omitempty"`
	CreatedByRunID        string   `json:"created_by_run_id,omitempty"`
	TraceID               string   `json:"trace_id,omitempty"`
	Harness               string   `json:"harness,omitempty"`
	Model                 string   `json:"model,omitempty"`
	Provider              string   `json:"provider,omitempty"`
}

type CreateRemediationFromFindingInput struct {
	ProjectID               string   `json:"project_id,omitempty"`
	FindingRef              string   `json:"finding_ref"`
	FindingStatus           string   `json:"finding_status"`
	Title                   string   `json:"title"`
	Summary                 string   `json:"summary"`
	Severity                string   `json:"severity,omitempty"`
	OwnerAgent              string   `json:"owner_agent,omitempty"`
	ImplementationAgentID   string   `json:"implementation_agent_id,omitempty"`
	CreatedByRunID          string   `json:"created_by_run_id,omitempty"`
	TraceID                 string   `json:"trace_id,omitempty"`
	PermissionSnapshotRef   string   `json:"permission_snapshot_ref,omitempty"`
	GitBaseRef              string   `json:"git_base_ref,omitempty"`
	GitBranchRef            string   `json:"git_branch_ref,omitempty"`
	GitWorktreeRef          string   `json:"git_worktree_ref,omitempty"`
	FilesToRead             []string `json:"files_to_read,omitempty"`
	FilesToEdit             []string `json:"files_to_edit,omitempty"`
	LikelyFilesAffected     []string `json:"likely_files_affected,omitempty"`
	EvidenceRefs            []string `json:"evidence_refs,omitempty"`
	VerificationRequirement string   `json:"verification_requirement"`
	ReviewGate              string   `json:"review_gate,omitempty"`
	ActivatePlan            bool     `json:"activate_plan,omitempty"`
}

type CreateRemediationFromFindingResult struct {
	WorkPlan         projectworkplan.WorkPlan `json:"work_plan"`
	WorkTask         projectworkplan.WorkTask `json:"work_task"`
	ReviewTask       projectworkplan.WorkTask `json:"review_task,omitempty"`
	Automation       Automation               `json:"automation"`
	ReviewAutomation Automation               `json:"review_automation,omitempty"`
	Activated        bool                     `json:"activated"`
}

type DirtyScopeRecoveryOptions struct {
	AllowedSupportPathspecs []string
	PathspecResolver        func(projectID string) []string
}

type EvidenceGovernance interface {
	CreateActionRef(context.Context, GovernanceActionInput) (string, error)
	CreateOutcomeRef(context.Context, GovernanceOutcomeInput) (string, error)
}

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

type ExecutorOptions struct {
	Enabled               bool
	RunnerEnabled         bool
	RunnerExecution       string
	PollInterval          time.Duration
	GlobalWorkerCount     int
	PerProjectWorkerLimit int
	PerAgentWorkerLimit   int
	ProjectIDs            []string
}

type GovernanceActionInput struct {
	ProjectID    string
	AutomationID string
	RunID        string
	TaskID       string
	ActionKind   string
}

type GovernanceConfidenceInput struct {
	ProjectID    string
	RunID        string
	TaskID       string
	ClaimRefs    []string
	EvidenceRefs []string
	VerifierRefs []string
	ReviewRefs   []string
	OutcomeRef   string
}

type GovernanceKnowledgeCandidateInput struct {
	ProjectID     string
	RunID         string
	TaskID        string
	ClaimRefs     []string
	EvidenceRefs  []string
	VerifierRefs  []string
	ReviewRefs    []string
	OutcomeRef    string
	ConfidenceRef string
}

type GovernanceOptions struct {
	Evidence   EvidenceGovernance
	Confidence ConfidenceGovernance
	Knowledge  KnowledgeGovernance
}

type GovernanceOutcomeInput struct {
	ProjectID     string
	AutomationID  string
	RunID         string
	TaskID        string
	AttemptID     string
	Status        string
	DurationMS    int64
	VerifierRefs  []string
	EvidenceRefs  []string
	ClaimRefs     []string
	ReviewRefs    []string
	KnowledgeRefs []string
}

type HeartbeatRunInput struct {
	ProjectID string `json:"project_id,omitempty"`
	RunID     string `json:"run_id"`
	ClaimID   string `json:"claim_id"`
	RunnerID  string `json:"runner_id,omitempty"`
}

type KnowledgeGovernance interface {
	CreateCandidateRef(context.Context, GovernanceKnowledgeCandidateInput) (string, error)
}

type Options struct {
	Enabled                           bool
	RunnerEnabled                     bool
	RequireCodexWhenAvailable         bool
	AllowManualRunner                 bool
	RunnerExecution                   string
	MaxParallelTasks                  int
	DefaultMaxRuntime                 time.Duration
	ExternalRunLeaseTTL               time.Duration
	DefaultMaxRetries                 int
	RecoveryMaxReplacementRunsPerTask int
	// ReworkBudgetPerTask is the maximum number of rework cycles a task may
	// undergo before it transitions to failed with outcome
	// rework_budget_exhausted. Defaults to 3 (defaultReworkBudgetPerTask). This
	// budget is INDEPENDENT from RecoveryMaxReplacementRunsPerTask: rework
	// exhaustion does not consume the fatal-retry budget (R5 partition).
	ReworkBudgetPerTask int
	// ClaimFullReconcileCooldown bounds how often a runner performs a full
	// reconciliation sweep during ClaimNextRun for a given project. Defaults to
	// 30s (defaultClaimFullReconcileCooldown) when zero. Per the automation
	// pipeline policy this runtime knob must be server/project TOML config.
	ClaimFullReconcileCooldown time.Duration
	// ClaimBroadReconcileTaskBatchLimit bounds project-wide ready/promotion work
	// performed by the broad ClaimNextRun reconcile pass. Defaults to
	// defaultClaimBroadReconcileTaskBatchLimit when zero. Per the automation
	// pipeline policy this runtime knob must be server/project TOML config.
	ClaimBroadReconcileTaskBatchLimit int
	// LeaseReaperInterval is the interval at which a background goroutine
	// reclaims expired-lease runs. Defaults to 60s when zero. Per the automation
	// pipeline policy this runtime knob must be server/project TOML config.
	LeaseReaperInterval time.Duration
	// ReviewedCloseoutReconcilerInterval is the interval at which a background
	// goroutine closes reviewed-open Work Tasks and releases their dependents,
	// independent of the throttled ClaimNextRun full-reconcile cascade. Defaults
	// to defaultReviewedCloseoutReconcilerInterval (20s) when zero. Per the
	// automation pipeline policy this runtime knob must be server/project TOML
	// config.
	ReviewedCloseoutReconcilerInterval time.Duration
	// AutomationReconcilerInterval is the interval at which a background goroutine
	// runs the full claim reconcile cascade per project, independent of the
	// throttled ClaimNextRun full-reconcile cascade. Without this, a starved claim
	// path (slow graph storage / heavy runner churn) can leave the reconcile steps
	// (ready-task queuing, plan completion, stale-claim release, review queuing)
	// effectively unrun, stalling pipelines. Defaults to
	// defaultAutomationReconcilerInterval (20s) when zero. Per the automation
	// pipeline policy this runtime knob must be server/project TOML config.
	AutomationReconcilerInterval time.Duration
	// ReviewGateTimeout is the maximum duration a task may stay in
	// needs_review/verifying without a review ref before the reconciler
	// auto-grants a review exemption (when the task has implementation
	// evidence). Default 0 = disabled. Per the automation pipeline policy this
	// runtime knob must be server/project TOML config.
	ReviewGateTimeout time.Duration
	// MaxFindingsPerAudit bounds how many confirmed high-confidence findings a
	// single area-bug-audit run will remediate. Findings beyond the cap are
	// recorded as superseded (never dropped). Default applied in the service
	// constructor (defaultMaxFindingsPerAudit = 10). Per-call MCP overrides are
	// clamped to maxFindingsPerAuditCeiling (50). Per the automation pipeline
	// policy this runtime knob must be server/project TOML config.
	MaxFindingsPerAudit   int
	CodexBinaryPath       string
	Agents                []AutomationAgent
	PermissionResolver    PermissionResolver
	Governance            GovernanceOptions
	WorkPlanStatusTrigger WorkPlanStatusTriggerOptions
	DirtyScopeRecovery    DirtyScopeRecoveryOptions
}

type PermissionCheckInput struct {
	ProjectID       string
	AutomationID    string
	AutomationRef   string
	AgentID         string
	PermissionRef   string
	RunnerKind      string
	RunnerExecution string
}

type PermissionResolver interface {
	CheckAutomationPermission(context.Context, PermissionCheckInput) (PermissionSnapshotMetadata, error)
}

type PermissionSnapshotMetadata struct {
	PermissionRef      string
	AgentID            string
	AllowedRunnerKinds []string
	DeniedCommands     []string
}

type ResetGitOpsRecoveryInput struct {
	ProjectID string `json:"project_id,omitempty"`
	RunID     string `json:"run_id,omitempty"`
}

type RunCondition struct {
	Status  string
	ClaimID string
}

type RunFilter struct {
	ProjectID         string `json:"project_id,omitempty"`
	AutomationID      string `json:"automation_id,omitempty"`
	AgentID           string `json:"agent_id,omitempty"`
	PlanID            string `json:"plan_id,omitempty"`
	Status            string `json:"status,omitempty"`
	OrchestratorRunID string `json:"orchestrator_run_id,omitempty"`
	FailureCategory   string `json:"failure_category,omitempty"`
	WorkTaskStatus    string `json:"work_task_status,omitempty"`
}

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

type Store interface {
	CreateAutomation(context.Context, Automation) (Automation, error)
	GetAutomation(context.Context, string, string) (Automation, error)
	ListAutomations(context.Context, AutomationFilter) ([]Automation, error)
	UpdateAutomation(context.Context, Automation) (Automation, error)
	CreateRun(context.Context, AutomationRun) (AutomationRun, error)
	GetRun(context.Context, string, string) (AutomationRun, error)
	ListRuns(context.Context, RunFilter) ([]AutomationRun, error)
	UpdateRun(context.Context, AutomationRun) (AutomationRun, error)
	// ClaimRun atomically transitions a run from RunStatusQueued to the
	// supplied next value (the service sets Status=RunStatusClaiming and the
	// claim/runner identity before calling). It returns ErrClaimRace if the
	// persisted run is no longer Queued (another claimer won), ErrNotFound if
	// the run does not exist, and otherwise the written run. The read+guard+
	// write happens atomically under the store's own lock so the claim
	// transition is correct without an external mutex.
	ClaimRun(context.Context, AutomationRun) (AutomationRun, error)
	// UpdateRunIf conditionally applies next only when the persisted run's
	// Status and ClaimID match the expected RunCondition. It returns
	// ErrConditionMismatch if they diverged (a concurrent claim/state change
	// won), ErrNotFound if the run does not exist, and otherwise the written
	// run. The read+guard+write is atomic under the store's own lock so two
	// concurrent guarded writes cannot both apply. Reconcile terminal-write
	// guards use this to avoid clobbering a concurrently-claimed run.
	UpdateRunIf(context.Context, RunCondition, AutomationRun) (AutomationRun, error)
	CreateAttempt(context.Context, AutomationAttempt) (AutomationAttempt, error)
	CreateParallelBatch(context.Context, AutomationParallelBatch) (AutomationParallelBatch, error)
	GetParallelBatch(context.Context, string, string) (AutomationParallelBatch, error)
	// PurgeAutomationsByStatus permanently deletes automation nodes matching the
	// given project + status filter (e.g. "cancelled"). Used by
	// PurgeCancelledAutomations to clean up stale clutter that slows the
	// reconciler's claim-next scan. Returns the count of deleted nodes.
	// Associated runs/attempts are cleaned via relationship cascade in the
	// graph layer's DeleteNodes.
	PurgeAutomationsByStatus(context.Context, string, string) (int, error)
	// PurgeRunsByStatus permanently deletes automation-run nodes matching the
	// given project + status (e.g. "completed"). Used to clean up thousands of
	// historical terminal runs that slow the reconciler's claim-next scan.
	// Only terminal statuses may be purged. Returns the count deleted.
	PurgeRunsByStatus(context.Context, string, string) (int, error)
	// DeleteAutomation permanently removes a single automation definition node
	// by id. It does NOT remove that automation's runs (call
	// DeleteRunsByAutomation first). Scoped by project; idempotent (nil when
	// absent). Used by the governed chain-run delete cascade.
	DeleteAutomation(context.Context, string, string) error
	// DeleteRunsByAutomation permanently removes every run node owned by the
	// given automation id. Scoped by project. Returns the count removed.
	// Idempotent (0, nil) when none exist. Used by the governed chain-run
	// delete cascade.
	DeleteRunsByAutomation(context.Context, string, string) (int, error)
}

type SubmitRunInput struct {
	ProjectID         string   `json:"project_id,omitempty"`
	AutomationID      string   `json:"automation_id"`
	PlanID            string   `json:"plan_id,omitempty"`
	TaskID            string   `json:"task_id,omitempty"`
	OwnerAgent        string   `json:"owner_agent,omitempty"`
	RunnerKind        string   `json:"runner_kind,omitempty"`
	OrchestratorRunID string   `json:"orchestrator_run_id,omitempty"`
	ParentRunID       string   `json:"parent_run_id,omitempty"`
	EvidenceRefs      []string `json:"evidence_refs,omitempty"`
	VerifierRefs      []string `json:"verifier_result_refs,omitempty"`
	SafeNextAction    string   `json:"safe_next_action,omitempty"`
}

type UpdateAutomationStatusInput struct {
	ProjectID    string `json:"project_id,omitempty"`
	AutomationID string `json:"automation_id"`
	Status       string `json:"status"`
	RunID        string `json:"run_id,omitempty"`
	TraceID      string `json:"trace_id,omitempty"`
}

type WorkPlanStatusTriggerOptions struct {
	Enabled  bool
	Statuses []string
}

type WorkTaskAPI interface {
	GetWorkPlan(context.Context, string, string) (projectworkplan.WorkPlan, error)
	GetWorkTask(context.Context, string, string) (projectworkplan.WorkTask, error)
	ListWorkTasks(context.Context, projectworkplan.WorkTaskFilter) ([]projectworkplan.WorkTask, error)
	ListOpenWorkTasks(context.Context, projectworkplan.WorkTaskFilter) ([]projectworkplan.WorkTask, error)
	ClaimWorkTask(context.Context, projectworkplan.WorkTaskActionInput) (projectworkplan.WorkTask, error)
	StartWorkTask(context.Context, projectworkplan.WorkTaskActionInput) (projectworkplan.WorkTask, error)
	AttachEvidence(context.Context, projectworkplan.AttachInput) (projectworkplan.Attachment, error)
	AttachVerifierResult(context.Context, projectworkplan.AttachInput) (projectworkplan.Attachment, error)
	AttachReviewResult(context.Context, projectworkplan.AttachInput) (projectworkplan.Attachment, error)
	CompleteWorkTask(context.Context, projectworkplan.WorkTaskActionInput) (projectworkplan.WorkTask, error)
	FailWorkTask(context.Context, projectworkplan.WorkTaskActionInput) (projectworkplan.WorkTask, error)
	BlockWorkTask(context.Context, projectworkplan.WorkTaskActionInput) (projectworkplan.WorkTask, error)
	// ResetWorkTaskRecovery clears a task's replacement-retry-limit block. Used by
	// ForceCancelRun (FM-3) so that cancelling a terminal retry-limit run also
	// unblocks the parent task atomically, instead of leaving it blocked with a
	// stale TraceID and no recovery marker.
	ResetWorkTaskRecovery(context.Context, projectworkplan.WorkTaskActionInput) (projectworkplan.WorkTask, error)
}