engine

type AgentAdvert struct {
	Adapter string
	Harness string
	Model   string
	Family  string
	Account string
	Classes []string
	// Effort is the reasoning-effort level the agent runs at; empty when
	// unset. It is not part of the agent's key: outcomes group by harness
	// and model.
	Effort string
	// Tools is the claude worker scope the runner recorded (§5.2), the
	// patterns joined by "+" or "none"; "" for a harness brigada does not
	// scope.
	Tools string
}

type AmendPlanResult struct {
	PlanID     int64
	State      string
	Added      []CreatedTask
	Cancelled  []int64
	Retargeted []int64
	Retiered   []int64
	Respecced  []int64
	Started    []CreatedTask
	Held       []HeldTask
	Reasons    []string
}

type Answer string

type AnswerResult struct {
	Answer     Answer
	QuestionID int64
	JobID      int64
	Run        int
}

type ArtifactInfo struct {
	ID        int64  `json:"id"`
	JobID     int64  `json:"job_id"`
	ProjectID int64  `json:"project_id"`
	Kind      string `json:"kind"`
	Path      string `json:"path"`
	Size      int64  `json:"size"`
	SHA256    string `json:"sha256"`
	CreatedAt string `json:"created_at"`
}

type AskResult struct {
	ProjectID int64       `json:"project_id"`
	EventID   int64       `json:"event_id"`
	Outcome   WakeOutcome `json:"outcome"`
	// HoldID names the attach that holds the foreman when the message
	// waits for it (§4.2 item 3); 0 otherwise.
	HoldID int64 `json:"hold_id,omitempty"`
	// LimitedUntil is the reset time (RFC3339) of a limited foreman
	// (§4.4); empty when the outcome is limited and the time unknown, and
	// for every other outcome.
	LimitedUntil string `json:"limited_until,omitempty"`
}

type AttachResult struct {
	Answer Answer
	HoldID int64 // the created hold; a busy second attach names the live hold
	JobID  int64 // a busy answer names the live foreman turn, when that made it busy
	// ForemanToken is the hold-scoped foreman token (§12.1): it works
	// while the hold lives and dies with the hold. Empty on busy.
	ForemanToken  string
	RepoURL       string
	DefaultBranch string
	LandTarget    string // the effective land target; the default branch when unset
	Harness       string
	Model         string
	Effort        string // the foreman's reasoning-effort level; ” = unset
	SessionID     string // the key's current harness session id; ” = none
	Prompt        string // the opening prompt
	ExpiresAt     time.Time
}

type CanonReport struct {
	// Rewritten counts the projects whose repo_url or transport changed.
	Rewritten int
	// Collisions are groups of project ids that canonicalize to the same
	// repository, by canonical form. Their rows are left untouched.
	Collisions map[string][]int64
	// Failed maps a project id to why its repo_url did not canonicalize
	// (the URL itself is never quoted). Those rows stay as they are.
	Failed map[int64]string
}

type CapacityAgent struct {
	ID       int64  `json:"id"`
	RunnerID int64  `json:"runner_id"`
	Harness  string `json:"harness"`
	Model    string `json:"model"`
	Tier     string `json:"tier"`
	// Effort is the agent's configured reasoning effort from its runner's
	// --agent effort=, or "default" when none is set.
	Effort  string `json:"effort"`
	Account string `json:"account"`
	// Cap is the effective cap — the smallest of the runner, account
	// and model caps on the agent's path — and CapLayer names the
	// layer that sets it (the caps package's layer names, or "none").
	// A nil Cap means no layer caps the agent; a Cap of 0 means capped
	// at nothing, which is different from not capped (§8.1).
	Cap      *int   `json:"cap"`
	CapLayer string `json:"cap_layer"`
	// Running counts the jobs on the agent — leased or running, the
	// ones that recorded it. A queued job holds no agent and never
	// counts (§12.2).
	Running int `json:"running"`
	// Quota is the agent's quota state (§8): ready, cooling — with
	// CoolingUntil, the store's UTC text — or broken. Broken wins over
	// cooling: a broken agent takes nothing whatever its cooling says.
	Quota        string `json:"quota"`
	CoolingUntil string `json:"cooling_until,omitempty"`
	// Cost is the agent's cost weight (§8.1): the configured weight of
	// its (harness, model) pair, 1 when the config names none.
	Cost int `json:"cost"`
	// Tools is a claude worker agent's shell scope as its runner
	// advertised it (§5.2): Claude Code patterns joined by "+", or
	// "none". Empty for a harness brigada does not scope.
	Tools string `json:"tools,omitempty"`
}

type CapacityHeadroom struct {
	ProjectID int64  `json:"project_id"`
	Account   string `json:"account"`
	Cap       *int   `json:"cap"`
}

type CapacityLayer struct {
	Layer string `json:"layer"` // the caps package's layer names: runner, account, model, plan, global
	// RunnerID names a runner layer's instance, Account an account's,
	// Model a capped model's and PlanID an active plan's.
	RunnerID int64  `json:"runner_id,omitempty"`
	Account  string `json:"account,omitempty"`
	Model    string `json:"model,omitempty"`
	PlanID   int64  `json:"plan_id,omitempty"`
	// Cap is the instance's cap; nil means the layer is not capped. A
	// runner entry carries the folded cap — the smaller of the
	// config's and the one the runner advertised (§8.1).
	Cap *int `json:"cap"`
	// Use counts the live jobs through the instance; Queue counts the
	// queued jobs the instance holds (§12.2).
	Use   int `json:"use"`
	Queue int `json:"queue"`
}

type CapacitySnapshot struct {
	Agents []CapacityAgent `json:"agents"`
	Layers []CapacityLayer `json:"layers"`
	// Headroom lists the accounts reserved for a foreman (§8.2), one
	// per project and account; empty when no project has one or the
	// rule is off.
	Headroom []CapacityHeadroom `json:"headroom,omitempty"`
}

type Completion struct {
	Usage       *adapter.Usage
	WallSeconds *float64
	Result      string
	Error       string
	CheckResult string
	SessionID   string
	Outcome     string
	// ErrorKind sorts an Error — "limit" when the CLI hit its
	// subscription limit (§4.4), "setup" or "infra" when the job's own
	// environment or plumbing failed (§5.7, §5.1) — and LimitUntil is
	// the reset time then, RFC3339, empty when unknown.
	ErrorKind  string
	LimitUntil string
	// StaleDropped names the target branch whose stale waiting ref a
	// land job deleted (§7.1): the landings that waited on it land again.
	StaleDropped string
}

type Config struct {
	// Now is the engine's clock; tests inject one so they never sleep.
	Now func() time.Time
	// LeaseTTL is how long a lease lasts without a heartbeat (§5.1).
	LeaseTTL time.Duration
	// ReleaseExclude is how long a releasing runner doesn't see the job
	// it gave back: other runners go first, and a lone runner may retry
	// once the exclusion lapses.
	ReleaseExclude time.Duration
	// MaxAttempts is how many leases a job may lose before it fails as
	// "runner lost N times" instead of being offered again.
	MaxAttempts int
	// QueueTTL is how long a queued job waits for a lease before it
	// fails, so it cannot wedge its key forever.
	QueueTTL time.Duration
	// HardCaps is the wall-time cap per job kind, measured from the
	// job's current lease (§5.6). Entries here override the
	// defaults for their kind only.
	HardCaps map[Kind]time.Duration
	// RoundCaps are the default per-task round caps; a task's caps JSON
	// (fix_rounds, review_rounds, restart) overrides them per task.
	RoundCaps RoundCaps
	// ExactRoundCaps, when set, replaces the default round caps as given,
	// zeros included (RoundCaps reads zero as "the default"). The config
	// file's rounds.* keys arrive here.
	ExactRoundCaps *RoundCaps
	// Review is the engine-wide default tier, effort and family rule of a
	// review (§7, §8, issue #126); a task's own review_tier and
	// review_effort win over its tier and effort.
	Review ReviewConfig
	// TaskAutoRetry retries a transient work failure once on another ready
	// agent (§3). Nil keeps the default, on; false parks immediately.
	TaskAutoRetry *bool
	// PlanReview is the engine-wide default of the plan review (§6.2):
	// nil keeps the default, on. A project's plan_review setting
	// overrides it per project.
	PlanReview *bool
	// ForemanWakeBudget is how many foreman turns a project may be woken
	// into per UTC day (§4.3); zero — the default — keeps
	// defaultForemanWakeBudget. The count is of the project's foreman
	// jobs, every one of them: turns this engine wakes and turns a person
	// submits by hand alike.
	ForemanWakeBudget int
	// Caps are the layered concurrency caps and cost weights (§8.1),
	// as the config named them; the zero value caps nothing. A runner's
	// own advertised cap folds into the runner layer.
	Caps caps.Limits
	// DataDir is where the engine keeps its artifact blobs (§9), laid
	// out content-addressed under artifacts/<sha256[:2]>/<sha256>. Zero
	// derives the directory of the store file; a store with no file of
	// its own keeps zero, and artifact uploads answer that plainly.
	DataDir string
	// MaxArtifactBytes caps one artifact upload (§9); zero keeps the
	// 64 MiB default.
	MaxArtifactBytes int64
	// Retention is how long messages and artifacts are kept before the
	// sweep prunes them (§9); zero — the default — keeps everything.
	// The event log is never pruned.
	Retention time.Duration
	// NewLeaseID mints lease ids: <owner>-<random hex>.
	NewLeaseID func(owner int64) (string, error)
	// NewLeaseToken mints the secret of a lease-scoped foreman token
	// (§12.1): random hex, returned once in the grant and stored only
	// as its sha256.
	NewLeaseToken func() (string, error)
	// Rand is the uniform source, a float in [0, 1), that the agent
	// ranking samples from (§8); tests inject it to pin the pick.
	Rand func() float64
	// LimitCooling is how long a task job's limit with no known reset
	// cools its account (§8 "Quota"); zero keeps 30 minutes.
	LimitCooling time.Duration
	// FailureStreak is how many consecutive failed completions by one
	// agent mark it broken (§8 "Health"); zero keeps 2.
	FailureStreak int
	// RunnerStale is how long a runner may go unseen before the sweep
	// marks its agents broken (§8 "Health"); zero keeps 15 minutes.
	RunnerStale time.Duration
	// ProbeDelay is how long an agent broken by repeated failures waits
	// before its first probe (§8 "Health"); zero keeps 5 minutes.
	ProbeDelay time.Duration
	// ProbeMaxDelay caps the growing delay between probes after failed
	// ones (§8 "Health"); zero keeps 1 hour.
	ProbeMaxDelay time.Duration
	// SweepInterval is how often the engine sweeps when the lifecycle's
	// idle ticker drives it (§13): the tick interval the sweep's
	// suspension check measures a gap against. Zero keeps the default,
	// the lifecycle's idle tick.
	SweepInterval time.Duration
	// PlanFiles turns the plan-file mirror on (§6.4): after each plan
	// change the engine pushes the plan's file to the project's remote.
	// Off by default — the mirror runs git against the project's repo URL —
	// and on in the running engine.
	PlanFiles bool
	// PlanFileRetry is how long a failed push holds the next attempt back;
	// zero keeps 30 seconds.
	PlanFileRetry time.Duration
	// PlanFileTimeout bounds one plan's fetch, commit and push; zero keeps
	// two minutes.
	PlanFileTimeout time.Duration
	// SnapshotDir is where the engine snapshots its store (§6.4): a
	// directory outside the store's own. Empty — the default — takes no
	// snapshots.
	SnapshotDir string
	// SnapshotEvery is the interval between snapshots; zero keeps 24
	// hours. Tests move it; the shipped engine does not.
	SnapshotEvery time.Duration
	// SnapshotKeep is how many snapshots stay; zero keeps 7.
	SnapshotKeep int
	// DefaultReviewer is the harness a standalone review (§7, `brigada
	// review --branch`) goes to when the author's family cannot be
	// told; empty = none, and such a review is then refused.
	DefaultReviewer string
	// BranchTrailers reads the Co-Authored-By trailer values of the
	// commits a branch holds beyond its base, one per line, from the
	// repo at repoURL; a standalone review's author-family fallback.
	// Nil keeps the git-backed default; tests inject it.
	BranchTrailers func(ctx context.Context, repoURL, base, branch string) (string, error)
	// IssueFetch reads one issue or pull request of the repository at
	// repoURL (§12.2 issue_read): GET requests alone. Nil keeps the
	// gh-backed default — the user's own gh login on the engine's host;
	// tests inject it so no test reaches the network.
	IssueFetch func(ctx context.Context, repoURL string, number int, comments bool) (*Issue, error)
	// Warnf logs the warnings of work the engine does best-effort, the
	// plan-file mirror's failed pushes among them; nil logs to the
	// standard logger.
	Warnf func(format string, args ...any)
}

type ConfigChange struct {
	Key string `json:"key"`
	Old string `json:"old"`
	New string `json:"new"`
}

type CoolingAgent struct {
	ID      int64  `json:"id"`
	Harness string `json:"harness"`
	Model   string `json:"model"`
	Account string `json:"account"`
	Until   string `json:"until"`
}

type CreatePlanResult struct {
	Answer Answer
	PlanID int64
	TaskID int64
	JobID  int64
	Run    int
	Tasks  []CreatedTask
	// State is the plan's: "active", or planAwaitingApproval when the
	// approval limit holds it (§6.3), with Reasons — one phrase each —
	// saying why. A held plan queued no job: TaskID, JobID and Run are
	// zero.
	State   string
	Reasons []string
}

type CreatedTask struct {
	TaskID int64
	Name   string
	JobID  int64
	// contains filtered or unexported fields
}

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

type ExtraRepo struct {
	// Name is [a-z][a-z0-9_-]*; it names the checkout directory and the
	// variable BRIGADA_REPO_<NAME>.
	Name string `json:"name"`
	Repo string `json:"repo"`
	URL  string `json:"url,omitempty"`
	// Ref is a branch, tag or commit; empty = the repository's default
	// branch.
	Ref string `json:"ref,omitempty"`
}

type ExtraReposSpec struct {
	Repos  []ExtraRepo `json:"repos"`
	Source string      `json:"source"`
	Hash   string      `json:"hash,omitempty"`
}

type ForemanInbox struct {
	Events       []string              `json:"events"`
	UserMessages []foreman.UserMessage `json:"user_messages"`
}

type ForemanSetting struct {
	ProjectID int64  `json:"project_id"`
	RepoURL   string `json:"repo_url"`
	Harness   string `json:"harness"`
	Model     string `json:"model"`
	// Effort is the foreman's reasoning-effort level; empty when unset.
	Effort string `json:"effort,omitempty"`
	// Unserved is set on the answer to a choice when no registered runner
	// agent offers the foreman class for the chosen harness/model pair: the
	// foreman's turns will wait until one does. It says nothing of a
	// registered agent that is only busy, cooling or broken.
	Unserved bool `json:"unserved,omitempty"`
}

type HeldJob struct {
	ID     int64  `json:"id"`
	TaskID int64  `json:"task_id,omitempty"`
	Kind   string `json:"kind"`
	Layer  string `json:"layer"`
	Since  string `json:"since,omitempty"`
	Agent  string `json:"agent,omitempty"`
	Until  string `json:"until,omitempty"`
}

type HeldTask struct {
	TaskID int64
	Name   string
	Reason string
}

type HistoryQuery struct {
	ProjectID int64
	TaskID    int64
	JobID     int64
	Since     string
	Limit     int
	Last      bool
}

type ImportResult struct {
	// Hash is the hash of the content imported.
	Hash string `json:"hash"`
	// NeedsConfirm: a first import found hand-set values the file would
	// replace (Diffs); nothing was written and the caller must repeat the
	// import with Accept set.
	NeedsConfirm bool `json:"needs_confirm,omitempty"`
	// Applied lists the keys whose store value the import changed, hand-set
	// replacements accepted on a first import included.
	Applied []ConfigChange `json:"applied,omitempty"`
	// Conflicts lists the local overrides that kept their value against a
	// different one in the file: Old is the local value, New the file's.
	Conflicts []ConfigChange `json:"conflicts,omitempty"`
	// Diffs lists, on a first import, the hand-set values the file differs
	// from: Old is the hand-set value, New the file's.
	Diffs []ConfigChange `json:"diffs,omitempty"`
	// Settings is the project's settings after the import; zero while
	// NeedsConfirm.
	Settings *ProjectSettings `json:"settings,omitempty"`
}

type InfraRetry struct {
	ID        int64  `json:"id"`
	TaskID    int64  `json:"task_id,omitempty"`
	Kind      string `json:"kind"`
	NotBefore string `json:"not_before"`
	Reason    string `json:"reason,omitempty"`
}

type Issue struct {
	Number int    `json:"number"`
	Title  string `json:"title"`
	Body   string `json:"body"`
	// Author is who opened the issue, the forge's login.
	Author string `json:"author,omitempty"`
	// URL is the issue's page on the forge, when it gave one.
	URL string `json:"url,omitempty"`
	// PullRequest says the number named a pull request, not an issue:
	// the same numbers space on GitHub either way.
	PullRequest bool `json:"pull_request,omitempty"`
	// Comments are the asked-for comments, oldest first, as the forge
	// lists them.
	Comments []IssueComment `json:"comments,omitempty"`
}

type IssueComment struct {
	Author string `json:"author,omitempty"`
	Body   string `json:"body"`
	// CreatedAt is when the forge says the comment landed, RFC3339.
	CreatedAt string `json:"created_at,omitempty"`
}

type JobInfo struct {
	ID             int64           `json:"id"`
	ProjectID      int64           `json:"project_id"`
	TaskID         int64           `json:"task_id"` // 0 for a foreman turn
	Kind           Kind            `json:"kind"`
	Mode           Mode            `json:"mode"`
	Key            string          `json:"key"`
	Status         string          `json:"status"`
	Prompt         string          `json:"prompt"`
	Harness        string          `json:"harness"`
	Labels         []string        `json:"labels"`
	Restart        bool            `json:"restart"`
	Followup       bool            `json:"followup"`
	Attempts       int64           `json:"attempts"`
	LeasedSeconds  int64           `json:"leased_seconds"`
	Result         json.RawMessage `json:"result,omitempty"`
	CheckResult    json.RawMessage `json:"check_result,omitempty"`
	LeaseExpiresAt string          `json:"lease_expires_at,omitempty"`
	// TranscriptID is the job's transcript artifact (§9), the run's own
	// record of itself; 0 until the runner uploaded one.
	TranscriptID int64 `json:"transcript_id,omitempty"`
	// CheckLogID is the job's newest check log artifact (§9); 0 when the
	// job ran no check or left no log.
	CheckLogID int64 `json:"check_log_id,omitempty"`
	// SetupLogID is the job's newest setup log artifact (§5.7); 0 when the
	// job ran no setup.
	SetupLogID int64  `json:"setup_log_id,omitempty"`
	CreatedAt  string `json:"created_at"`
	UpdatedAt  string `json:"updated_at"`
}

type Kind string

type LandDecision struct {
	TaskID   int64    `json:"task_id"`
	Released bool     `json:"released"` // true for an approval, false for a rejection
	Queued   bool     `json:"queued,omitempty"`
	JobID    int64    `json:"job_id,omitempty"`
	Settings []string `json:"settings_changed,omitempty"`
}

type LandMessage struct {
	Title         string `json:"title"`
	Spec          string `json:"spec"`
	Summary       string `json:"summary"`
	CommitMessage string `json:"commit_message,omitempty"`
	Family        string `json:"family"`
	Model         string `json:"model"`
}

type LandRetryResult struct {
	TaskID  int64  `json:"task_id"`
	Outcome string `json:"outcome"`
	JobID   int64  `json:"job_id,omitempty"`
	Reason  string `json:"reason,omitempty"`
}

type LandedCommit struct {
	TaskID int64  `json:"task_id"`
	Commit string `json:"commit"`
}

type LeaseGrant struct {
	JobID      int64
	LeaseOwner int64 // the runner the lease belongs to
	ProjectID  int64
	TaskID     int64 // 0 for a foreman turn
	Kind       Kind
	Mode       Mode
	Key        string
	Prompt     string
	LeaseID    string
	// LeaseExpiresAt is when the lease lapses without a heartbeat.
	LeaseExpiresAt time.Time
	// ForemanToken is the lease-scoped foreman token (§12.1, §12.2),
	// minted with the lease of a foreman turn and empty for every task
	// job. It is the secret's only appearance: it reaches the runner in
	// the grant and lives in the runner's memory alone — never a log,
	// an event or an error message, and the store keeps only its hash.
	ForemanToken string
	// Effort is the task job's mapped effort, with the agent default applied.
	Effort string
	// ForemanEffort is the project's chosen foreman effort level, set on a
	// foreman turn's grant only; ” = none chosen, the runner agent's own
	// effort stands.
	ForemanEffort string

	Harness string // the job's harness constraint; ” = any (§8)
	Agent   string // the harness of the agent the lease picked (§8); ” = none
	// AgentAdapter and AgentModel name the picked registration exactly for
	// every job kind; a harness alone can name several agents on a runner.
	AgentAdapter string
	AgentModel   string
	RepoURL      string // the task's own repo, else the project's (§6.1)
	BaseRef      string // the ref the worktree starts from; for a review, the diff's base end (§7)
	CheckCmd     string // the check the runner runs after a done (§5.5); ” = none — always for a review
	// WorkerTools is the project's worker_tools in its stored text, for a
	// work or fix job; ” = unset, the harness's default scope.
	WorkerTools string
	// Setup is the environment step the runner runs before the worker and
	// again before the check (§5.7); nil = the project had none.
	Setup *SetupSpec
	// ExtraRepos are the read-only repositories the runner checks out
	// beside the worktree (§5.8): the task's recorded list, the project's
	// default for a task-less review.
	ExtraRepos []ExtraRepo
	// ReviewBranch is the task's result branch a review job reviews
	// (§7): the runner's worktree sits at it, fetched from the remote,
	// and it is all the review reads — never pushed, never re-made.
	// Empty for every kind but review: a work job's worktree makes its
	// own branch. BaseRef and ReviewBranch together name the diff the
	// review prompt tells the reviewer to run.
	ReviewBranch string
	// ReviewSince is, for a re-review (§7), the head the review it
	// resumes judged: the runner's diff file holds the commits since it.
	// Empty for every other job.
	ReviewSince string
	// LandTarget is, for a land job (§7.1), the branch the task's diff is
	// squashed onto: land_target, or the project's default branch. Empty
	// for every other kind.
	LandTarget string
	// DefaultBranch is, for a land job (§7.1), the project's default
	// branch: the runner creates a land_target the remote does not have
	// yet from it. A foreman turn and a plan review carry it too: their
	// BaseRef is the land target, and the default branch is the fallback
	// when the remote lacks it (issue #122). Empty for every other kind.
	DefaultBranch string
	// LandMessage is, for a land job's squash phase (§7.1), the task
	// data the squash commit message is built from, as the hand-driven
	// land builds it from the API. nil for the push phase and every
	// other kind.
	LandMessage *LandMessage
	// LandCommit is, for a land job's push phase (§7.1), the commit the
	// landing already recorded: the runner pushes exactly it, no new
	// squash. Empty for the squash phase and every other kind.
	LandCommit string
	// Push is true for a land job's push phase (§7.1): the squash and
	// check already happened, and the runner pushes the recorded commit,
	// then runs after_land. False for the squash phase and every other
	// kind.
	Push bool
	// GatePush is the project's push gate a land job reads (§6.3): auto
	// pushes, ask records waiting for the user, never records the exact
	// push command without pushing. Empty for every other kind.
	GatePush string
	// AfterLand is the repo-relative command the runner runs after the
	// push, or after the landing when gate_push is never (§6.3). Empty =
	// none.
	AfterLand string
	// LandReady is the repo-relative command the runner runs before
	// landing (issue #87). Empty = none.
	LandReady string
	// SkipLandReady is the engine's mark that the land_ready gate's hold
	// was already released by an approval (issue #87): the runner runs
	// no command and lands. False on every grant but a released hold's.
	SkipLandReady bool
	// Branch is the branch the engine names a work or fix job to work
	// on (§5.1): a work job makes it from the base ref, a fix round
	// continues the task's current branch, and the runner builds and
	// pushes exactly it — never a name of its own choosing. Named once,
	// at the job's first lease, and kept by every later lease of the
	// same job. Empty for a review, which reads ReviewBranch and moves
	// nothing, and for a foreman turn, which belongs to no task.
	Branch string
	// ApprovedHead is, for a land job's squash phase (§7.1), the head of
	// Branch the approving review judged, as the author job's result
	// recorded it: the runner refuses to land any other. Empty when the
	// result recorded none.
	ApprovedHead string
	Attempt      int64 // leases taken on the job, this one included
	// ResumeSessionID is the harness session the key's last run ended
	// on (§4.2), for a session-mode job to resume; empty when the key
	// never ran or the job is fresh.
	ResumeSessionID string
	// SessionGen is the task's session generation (§5.1): how many
	// restarts the task has had at this lease, which names the attempt
	// the job belongs to. Every job of one attempt — its work job, the
	// fix rounds that resume the author's session, its reviews — leases
	// under one generation, and a restart moves it, so the runner can
	// name a worktree path the session's whole round shares: a harness
	// session belongs to the directory it started in. 0 for a foreman
	// turn and a task-less review, which no resume ties to a task.
	SessionGen int64
}

type Mode string

type NeedsYouItem struct {
	Kind   string `json:"kind"` // "task", "plan", "foreman" (a limited foreman, §4.4; ID is the project's, Title its repo URL) or "agent" (a broken one, §8; ID is the agent's, Title harness/model)
	ID     int64  `json:"id"`
	State  string `json:"state"`
	Title  string `json:"title"`
	Reason string `json:"reason,omitempty"`
	PlanID int64  `json:"plan_id,omitempty"` // the task's plan, when the entry is a task
	// ForemanHolds is true for a task parked at needs_foreman that the
	// foreman will handle (§10, foremanHolds.task): a live turn carries
	// its event, or an attached chat holds the project. The user's queue
	// leaves such a task out; the foreman's list keeps it.
	ForemanHolds bool `json:"foreman_holds,omitempty"`
	// A plan awaiting approval also carries what a coordinator shows the
	// user and quotes back (§4.6): the project's repo URL, the
	// plan's version — an amendment bumps it — and its tasks.
	RepoURL string       `json:"repo_url,omitempty"`
	Version int64        `json:"version,omitempty"`
	Tasks   []StatusTask `json:"tasks,omitempty"`
}

type PlanAmendment struct {
	Add      []PlanTask
	Cancel   []string
	Retarget []PlanRetarget
	Retier   []PlanRetier
	Respec   []PlanRespec
	// SkipApproved says the user themself approved the cancellations of
	// this amendment: only a user's token can say so, never the foreman's
	// own. Without it a cancelled task is an abandoned one, and the
	// planner's outcome counts it against the plan.
	SkipApproved bool
}

type PlanDecision struct {
	PlanID   int64
	State    string
	Tasks    []CreatedTask
	Settings []string
}

type PlanRecovery struct {
	Repo   string
	PlanID int64
	Action string
	Detail string
}

type PlanRespec struct {
	Task   string
	Spec   string
	Mode   string
	Skills []string
}

type PlanRetarget struct {
	Task string
	Deps []string
	// Base names the one of Deps the task stacks on, as PlanTask.Base
	// does; ” = the default rule. The task's earlier base goes with
	// its earlier dependencies.
	Base string
	// Continue names the one of Deps whose author's session the task
	// continues, as PlanTask.Continue does; ” = the earlier continued
	// dep goes with the earlier dependencies.
	Continue string
}

type PlanRetier struct {
	Task         string
	Tier         string
	Effort       string
	ReviewTier   string
	ReviewEffort string
	// Caps merges key by key into the task's own caps (fix_rounds,
	// review_rounds, restart; 0 to 10); nil changes none.
	Caps map[string]int
	// Skills, in order, replaces the task's recorded skills (§5.10) when
	// the task has not started; nil keeps them. The re-resolution copies
	// the current texts.
	Skills []string
}

type PlanTask struct {
	Title  string
	Name   string // ” = unnamed: nothing can depend on it
	Spec   string
	Check  string
	Class  string // ” = implement
	Tier   string // ” = standard
	Effort string // ” = the agent's own level
	// ReviewTier and ReviewEffort are the task's own tier and effort for
	// its reviews (§7, §8); ” = the engine default (review.tier,
	// review.effort).
	ReviewTier   string
	ReviewEffort string
	// Caps overrides the engine's round caps for this task, key by key
	// (fix_rounds, review_rounds, restart; 0 to 10); nil keeps them all.
	Caps map[string]int
	Deps []string
	// Base names the one of Deps whose result branch this task's work
	// starts from; ” = the only dep when there is exactly one, the
	// continued dep when Continue names one, else the project's default
	// branch.
	Base string
	// Continue names the one of Deps whose author's session this task's
	// first work job resumes (§6.1): the worker that wrote the dep's
	// approved result starts the new task warm, in its own session.
	// ” = start fresh like any other task.
	Continue string
	// ExtraRepos are the read-only repositories the task is given (§5.8).
	// nil = inherit the project default; non-nil, even empty, replaces it.
	ExtraRepos []ExtraRepo
	// Skills names, in order, the project's imported skills the task's
	// prompts carry (§5.10): resolved and copied onto the task once, at
	// creation; nil or empty = none.
	Skills []string
}

type Probe struct {
	AgentID int64  `json:"agent_id"`
	Adapter string `json:"adapter"`
	Harness string `json:"harness"`
	Model   string `json:"model"`
}

type Progress struct {
	LastProgressAt time.Time
	LastActivityAt time.Time
	Events         []string
	// Loop reports the runner's loop watch tripped (§5.6): the worker
	// repeats the same tool call. LoopCall names the call. The signal
	// routes to the foreman like a stall; the run is not stopped.
	Loop     bool
	LoopCall string
}

type ProjectConfig struct {
	// Repo is the canonical identity the file names.
	Repo string
	// InstructionsFile is the repo-relative path the file names under
	// instructions_file, "" when it sets none. The client reads it; the
	// text rides beside the file's bytes at import.
	InstructionsFile string
	// RoleFiles maps a role to the repo-relative path the nested
	// instructions map names for it; a role absent is not configured.
	// The 1.0 alias instructions_file stays in InstructionsFile.
	RoleFiles map[string]string
	// SkillsDir is the repo-relative skills directory skills_dir names,
	// "" when the key is absent.
	SkillsDir string
	// Values holds the stored JSON of each setting the file sets.
	Values map[string]json.RawMessage
}

type ProjectInfo struct {
	ProjectID   int64  `json:"project_id"`
	RepoURL     string `json:"repo_url"`
	Harness     string `json:"harness"`
	Model       string `json:"model"`
	ActivePlans int    `json:"active_plans"`
	NeedsYou    int    `json:"needs_you"`
}

type ProjectSettings struct {
	ProjectID int64          `json:"project_id"`
	RepoURL   string         `json:"repo_url"`
	Settings  []SettingValue `json:"settings"`
	// ImportHash is the hash of the project.yaml content last imported;
	// empty when none was.
	ImportHash string `json:"import_hash,omitempty"`
}

type ProjectStats struct {
	ProjectID int64      `json:"project_id"`
	RepoURL   string     `json:"repo_url"`
	Rows      []StatsRow `json:"rows"`
}

type PruneReport struct {
	Messages  int64 `json:"messages"`
	Artifacts int64 `json:"artifacts"`
	Files     int64 `json:"files"`
}

type PushApproveResult struct {
	// Released counts the landings moved from waiting to a queued push.
	Released int `json:"released"`
}

type Ranked struct {
	Agent  int64   `json:"agent"`
	Weight int     `json:"weight"`
	Draw   float64 `json:"draw"`
}

type RestartResult struct {
	Answer Answer
	JobID  int64
	Run    int
}

type RetireResult struct {
	Retired []int64       `json:"retired"`
	Plans   []RetiredPlan `json:"plans"`
}

type RetiredPlan struct {
	PlanID int64  `json:"plan_id"`
	State  string `json:"state"`
}

type ReviewBranchResult struct {
	Answer    Answer `json:"answer"`
	ProjectID int64  `json:"project_id"`
	JobID     int64  `json:"job_id"`
	Run       int    `json:"run,omitempty"`
	// Family is the author's family the reviewer must differ from; empty
	// when it could not be told and the default reviewer was taken.
	Family string `json:"family,omitempty"`
	// Source is where the family came from: job, trailer or default.
	// Empty when no witness named one and no default reviewer was
	// configured — the open placement prefer makes (issue #126).
	Source string `json:"source"`
}

type ReviewConfig struct {
	Tier   string // ReviewTierBelow or ReviewTierSame; ” = below
	Effort string // low, medium, high or max; ” = medium
	Family string // ReviewFamilyPrefer or ReviewFamilyRequire; ” = prefer
}

type RoleFileRemoval struct {
	Role string
	// Removed is the imported record that was deleted.
	Removed *RoleInstruction
	// Kept is the local record that kept its text against the dropped
	// key, the ErrRoleTextKept case of a role file the file no longer
	// names.
	Kept *RoleInstruction
}

type RoleInstruction struct {
	ProjectID int64  `json:"project_id"`
	RepoURL   string `json:"repo_url"`
	Role      string `json:"role"`
	// State is one of RoleStateNotConfigured, RoleStateEmptyByChoice,
	// RoleStateFile.
	State string `json:"state"`
	// Source is where the text came from: default (not configured),
	// generated (seeded from the embedded defaults), local or imported.
	Source string `json:"source"`
	// Version is the settings version the text is pinned to: the import
	// hash for an imported text, the defaults version for a generated
	// one, empty for a local text.
	Version string `json:"version,omitempty"`
	// Provenance is the one-line reading of the source, the way the
	// foreman's status shows it: "generated from <version>, by upgrade"
	// for a seeded text, the source word otherwise.
	Provenance string `json:"provenance"`
	Bytes      int    `json:"bytes"`
	Digest     string `json:"digest"`
	// Text is the effective text: the row's; empty for a role not
	// configured or an empty-by-choice row, for at run time the engine
	// never falls back to a text in the binary (§5.9).
	Text string `json:"text,omitempty"`
}

type RoleSnapshot struct {
	Text    string `json:"text,omitempty"`
	Source  string `json:"source,omitempty"`
	Version string `json:"version,omitempty"`
	Digest  string `json:"digest,omitempty"`
	Bytes   int    `json:"bytes"`
}

type RoundCaps struct {
	Fix     int
	Review  int
	Restart int
}

type SettingValue struct {
	Key     string `json:"key"`
	Value   string `json:"value"`
	Default bool   `json:"default"`
	Source  string `json:"source"`
	Hash    string `json:"hash,omitempty"`
}

type SetupSpec struct {
	Command        string   `json:"command"`
	CacheKeyFiles  []string `json:"cache_key_files,omitempty"`
	TimeoutMinutes int      `json:"timeout_minutes"`
	Source         string   `json:"source,omitempty"`
	Hash           string   `json:"hash,omitempty"`
}

type Skill struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	// For is the frontmatter's 'for:' — worker, reviewer or both; empty
	// on an import means both.
	For        string `json:"for,omitempty"`
	Text       string `json:"text"`
	Digest     string `json:"digest,omitempty"`
	TreeDigest string `json:"tree_digest,omitempty"`
}

type SkillFileDigest struct {
	Digest string `json:"digest"`
	Tree   string `json:"tree,omitempty"`
}

type Slot struct {
	ProjectID int64     `json:"project_id"`
	State     SlotState `json:"state"`
	HolderID  int64     `json:"holder_id,omitempty"`
	Label     string    `json:"label,omitempty"`
	Since     string    `json:"since,omitempty"`
	Events    []string  `json:"events,omitempty"`
}

type SlotState string

type StatsRow struct {
	AgentID            int64    `json:"agent_id"`
	Harness            string   `json:"harness"`
	Model              string   `json:"model"`
	Tier               string   `json:"tier"`
	Effort             string   `json:"effort,omitempty"` // the agent's effort level; outcomes still group by harness/model
	Account            string   `json:"account"`
	Runner             string   `json:"runner"`
	Live               bool     `json:"live"` // the runner was seen within the stats window
	Class              string   `json:"class"`
	Skills             int      `json:"skills"` // how many skills the tasks of the row carried (§5.10); rows with different counts are never pooled
	Attempts           int      `json:"attempts"`
	Successes          int      `json:"successes"`
	Score              float64  `json:"score"`
	InputTokens        *int64   `json:"input_tokens"`
	OutputTokens       *int64   `json:"output_tokens"`
	CachedInputTokens  *int64   `json:"cached_input_tokens"`
	ReasoningTokens    *int64   `json:"reasoning_tokens"`
	Tokens             *int64   `json:"tokens"`
	CostUSD            *float64 `json:"cost_usd"`
	WallSeconds        *float64 `json:"wall_seconds"`
	ModelCalls         *int64   `json:"model_calls"`
	CallsPerJob        *float64 `json:"calls_per_job"`
	CallsPerSuccess    *float64 `json:"calls_per_success"`
	CostPerSuccess     *float64 `json:"cost_per_success"`
	CostPerSuccessUnit string   `json:"cost_per_success_unit,omitempty"`
}

type StatusInfo struct {
	Pid       int64          `json:"pid"`
	StartedAt string         `json:"started_at"`
	Jobs      map[string]int `json:"jobs"`
	Running   []StatusJob    `json:"running"`
	// RunnerDraining is true while a runner has a restart drain pending
	// (§5.1): it finishes its running jobs and exits, and the status
	// renders the restart that waits behind them.
	RunnerDraining bool `json:"runner_draining,omitempty"`
	// ForemanMessages counts the user's messages waiting in the foreman
	// inbox (§4.2 item 3): queued while a chat is attached, a turn runs,
	// or the wake cannot happen; delivered ones are not counted.
	ForemanMessages int `json:"foreman_messages"`
	// Slots is who holds the foreman's live slot, per project (§4.6):
	// free, a headless turn or an attach, with the holder's label and
	// since when.
	Slots []Slot       `json:"slots"`
	Plans []StatusPlan `json:"plans"`
	// HiddenFinishedPlans counts the finished plans — done or
	// cancelled — the plans list left out (§10): the default keeps the
	// newest statusFinishedKeep, the all view lists every one. The
	// status views render it as the one summary line that says the
	// rest exist.
	HiddenFinishedPlans int            `json:"hidden_finished_plans,omitempty"`
	Report              *StatusReport  `json:"report,omitempty"`
	NeedsYou            []NeedsYouItem `json:"needs_you"`
	// ForemanHolds lists the needs-you entries the foreman holds (§10),
	// split out of NeedsYou for a caller that is not the foreman: the
	// engine's own Status keeps every entry in NeedsYou, and the API
	// moves the held ones here (SplitForemanHolds).
	ForemanHolds []NeedsYouItem `json:"foreman_holds,omitempty"`
	// Cooling lists the agents held back for quota (§8, §10): shown
	// beside the running jobs, never in the needs-you queue.
	Cooling []CoolingAgent `json:"cooling,omitempty"`
	// Held lists the queued jobs a full cap layer holds (§8.1); the
	// runner layer's are jobs waiting for a runner slot.
	Held []HeldJob `json:"held,omitempty"`
	// Retries lists the queued jobs waiting out an infrastructure
	// backoff (§5.1): the job's not-before and the failure's words.
	Retries []InfraRetry `json:"retries,omitempty"`
	// Instructions lists the projects in scope that have project
	// instructions (§5.9): source, version, size and digest; the text only
	// from StatusWithInstructions.
	Instructions     []StatusInstructions     `json:"instructions,omitempty"`
	RoleInstructions []StatusRoleInstructions `json:"role_instructions,omitempty"`
	Skills           []StatusSkill            `json:"skills,omitempty"`
}

type StatusInstructions struct {
	ProjectID int64  `json:"project_id"`
	RepoURL   string `json:"repo_url"`
	Source    string `json:"source"`
	// Version is the hash of the import the text came from; empty for a
	// local override.
	Version string `json:"version,omitempty"`
	Bytes   int    `json:"bytes"`
	Digest  string `json:"digest"`
	Text    string `json:"text,omitempty"`
}

type StatusJob struct {
	ID        int64  `json:"id"`
	TaskID    int64  `json:"task_id,omitempty"`
	Kind      string `json:"kind"`
	Status    string `json:"status"`
	Harness   string `json:"harness,omitempty"`
	Model     string `json:"model,omitempty"`
	Effort    string `json:"effort,omitempty"` // the agent's effort level; shown as model@effort
	LeasedAt  string `json:"leased_at,omitempty"`
	LastEvent string `json:"last_event,omitempty"`
}

type StatusPlan struct {
	ID      int64  `json:"id"`
	RepoURL string `json:"repo_url"`
	Title   string `json:"title"`
	State   string `json:"state"`
	// ReviewRound, ReviewVerdict and ReviewFindings are the plan review's
	// state (§6.2): the round under way while the plan reviews, and
	// the latest verdict and findings once a round has ended. The
	// findings are the event's whole text; the short views that render
	// them cut at their own bound and point to ReviewJob's history.
	ReviewRound    int    `json:"review_round,omitempty"`
	ReviewVerdict  string `json:"review_verdict,omitempty"`
	ReviewFindings string `json:"review_findings,omitempty"`
	ReviewJob      int64  `json:"review_job,omitempty"`
	// ReviewPlacement is the leased plan review's placement kind (issue
	// #126) when it is not cross_family: same_family, same_agent or
	// unknown. Empty for cross_family (the default, left unsaid), for a
	// plan not under review and for a review no reviewer has leased yet.
	ReviewPlacement string `json:"review_placement,omitempty"`
	// WaitingAmendment is true while the plan reviews with waiting
	// amendment work (§6.2): tasks an amendment added or respecified
	// under the running round, pending its verdict, which queues the
	// next round over them.
	WaitingAmendment bool         `json:"waiting_amendment,omitempty"`
	Tasks            []StatusTask `json:"tasks"`
}

type StatusReport struct {
	ProjectID int64  `json:"project_id"`
	JobID     int64  `json:"job_id"`
	CreatedAt string `json:"created_at"`
	Text      string `json:"text"`
}

type StatusRoleInstructions struct {
	ProjectID          int64  `json:"project_id"`
	RepoURL            string `json:"repo_url"`
	Role               string `json:"role"`
	State              string `json:"state"`
	Source             string `json:"source,omitempty"`
	Bytes              int    `json:"bytes"`
	Digest             string `json:"digest,omitempty"`
	GeneratedFrom      string `json:"generated_from,omitempty"`
	Edited             *bool  `json:"edited"`
	ChangedSinceImport *bool  `json:"changed_since_import"`
	Text               string `json:"text,omitempty"`
}

type StatusSkill struct {
	ProjectID   int64  `json:"project_id"`
	Name        string `json:"name"`
	Description string `json:"description"`
	Digest      string `json:"digest"`
	TimesUsed   int    `json:"times_used"`
	TreeDigest  string `json:"tree_digest,omitempty"`
	// ChangedSinceImport compares the client's current file and tree
	// digests with the imported ones; nil when the client sent none.
	ChangedSinceImport *bool `json:"changed_since_import"`
}

type StatusTask struct {
	Tier          string `json:"tier,omitempty"`
	EffectiveTier string `json:"effective_tier,omitempty"`
	Effort        string `json:"effort,omitempty"`
	// EffectiveEffort is the effort the escalation ladder runs the task
	// at (§8); it equals Effort until an effort step.
	EffectiveEffort string `json:"effective_effort,omitempty"`
	// ReviewTier and ReviewEffort are the task's own tier and effort for its
	// reviews (§7, §8); empty = the engine default (review.tier,
	// review.effort), which status leaves unsaid.
	ReviewTier   string `json:"review_tier,omitempty"`
	ReviewEffort string `json:"review_effort,omitempty"`
	// ReviewPlacement is the placement kind (issue #126) of the task's
	// latest review job while the task reviews, when that job was leased
	// and the kind is not cross_family: same_family, same_agent or
	// unknown. Empty otherwise: a review no reviewer has leased names
	// its unservable reason, never a placement.
	ReviewPlacement string `json:"review_placement,omitempty"`
	// Caps are the task's own round-cap overrides (§6.1); absent keys run
	// at the engine default.
	Caps map[string]int `json:"caps,omitempty"`
	ID   int64          `json:"id"`
	// Name is the task's plan name (§6.1), empty when it has none: the
	// short handle the plan tools name tasks by, shown so a tool's
	// caller can carry it back.
	Name   string `json:"name,omitempty"`
	Title  string `json:"title"`
	Class  string `json:"class"`
	State  string `json:"state"`
	Branch string `json:"branch"` // empty while the task has no result branch yet
	// Landed is true when the task's landing is recorded and not waiting
	// at the push gate (§7.1): the land job squashed it, or a Brigada-Task
	// trailer on the default branch was detected and recorded.
	Landed bool `json:"landed,omitempty"`
	// LandedCommit is the commit the task landed as on its target
	// (§7.1), from its landing record; empty when it has none.
	LandedCommit string `json:"landed_commit,omitempty"`
	// LandReady is the land_ready gate's target state for a done task
	// (issue #87): "ready" when its land job is queued or running,
	// "held by rule land_ready: <line>" when the gate's exit 1 held the
	// landing, and "waiting (retry at <time>, last exit <n>)" when the
	// gate answered not ready and the landing is requeued on the backoff.
	// Empty when the task is not done, not implement, already landed, or
	// held by another rule.
	LandReady string `json:"land_ready,omitempty"`
	// WaitingOn names the unfinished dependencies of a task that waits
	// on them (§6.1): each by its plan name, or "#id" when unnamed.
	WaitingOn []string `json:"waiting_on,omitempty"`
	// Continues names the dependency whose author's session the task's
	// first work job resumes (§6.1), by plan name or "#id"; empty when
	// the task continues none.
	Continues string `json:"continues,omitempty"`
	// Skills names the skills the task recorded (§5.10), in order.
	Skills []string `json:"skills,omitempty"`
}

type SubmitParams struct {
	// Key is the queue: 'task:<id>' for worker jobs, 'foreman:<project>'
	// for the foreman's turns. At most one live job exists per key.
	Key       string
	ProjectID int64
	TaskID    int64 // 0 for a foreman turn
	Kind      Kind
	Mode      Mode
	Prompt    string
	// Harness and Labels are placement constraints: the harness that
	// must run the job (” = any) and the labels a runner must offer in
	// full (§8).
	Harness string
	Labels  []string
	// Model is the model a foreman turn must run on, beside its harness:
	// only an agent offering exactly that pair may lease the turn. Empty on
	// every other job, and on a turn submitted without one, which follows
	// the project's own choice (foremanPairTx).
	Model string
	// ExcludeFamily is the family rule's exclusion (§7, §8): when set,
	// only an agent of another family that offers the review class may
	// lease the job. The engine sets it on a task's review job, from
	// the family of the author job's agent.
	ExcludeFamily string
	// ExcludeAgent is the retry rule's exclusion (§3, §7): when set,
	// that one agent may not lease the job. Work jobs have no family
	// rule; review retries also apply the review family and class rules.
	ExcludeAgent int64
	// RequireAgent is a placement pin (§3): when set, the one agent
	// the job must run on — the author's own, read from the latest work
	// or fix job — because the harness alone does not name it: another
	// runner may offer the same harness, and the author's runner may
	// hold a second agent of it. An automatic restart pins a different
	// eligible agent instead. A runner not offering the agent cannot
	// lease the job at all.
	RequireAgent int64
	// Round names the task's rounds budget this job spends (§7, §6.1):
	// roundFix for a fix round a failed check asked for, roundReview
	// for one a review's changes asked for — both counted as the task's
	// fix jobs — and roundRestart for a restart. Empty spends nothing
	// (a work job, a review job: §7 caps the review loop's fix rounds,
	// not the reviews themselves) and lets a plain fix submit spend a
	// fix round. RoundNone spends nothing even for a fix job: the
	// foreman's answer resumes the author's session without a round
	// (§3), so its job must clear the caps and the counts both.
	Round string
	// Restart marks the job as a restart round (§5.6): any live job on
	// the key is cancelled first, and the job counts toward the task's
	// restart cap.
	Restart bool
	// Branch is the branch a standalone review (no task) reads: the one
	// job whose branch the submit names, since no task row holds it. The
	// engine names the branch of every other job at its first lease.
	Branch string
	// NotBefore is the time before which the queued job may not be
	// leased (§3, §4.2): the engine's retry and re-wake delays write it
	// so a job does not fire again while the network is still down. The
	// zero value means the job is leasable at once.
	NotBefore time.Time
	// SkipLandReady marks the land job an approval queues to release the
	// land_ready gate's hold (issue #87): the runner runs no command and
	// lands. False on every other job.
	SkipLandReady bool
	// PromptMeta is what the job records beside its composed prompt
	// (§5.9 'Versioning'): the template's version and the digests of
	// the instruction and skill texts the prompt carried, so a
	// recorded prompt is reproducible. ” on a job whose prompt was
	// composed without guidance.
	PromptMeta string
}

type SubmitResult struct {
	Answer Answer
	// JobID is the created job, or the live job a pending submit
	// coalesced behind.
	JobID int64
	// Run is the key's run number when a job was created: how many jobs
	// the key has had, this one included.
	Run int
}

type SweepReport struct {
	Expired       []int64 // leases that lapsed; back to queued, keeping their lease ids
	HardCapped    []int64 // live jobs failed past their kind's hard cap
	QueueTimedOut []int64 // queued jobs that waited past the queue TTL without a lease
}

type TaskInfo struct {
	Tier          string `json:"tier,omitempty"`
	EffectiveTier string `json:"effective_tier,omitempty"`
	Effort        string `json:"effort,omitempty"`
	ID            int64  `json:"id"`
	ProjectID     int64  `json:"project_id"`
	PlanID        int64  `json:"plan_id"`
	Title         string `json:"title"`
	State         string `json:"state"`
	RepoURL       string `json:"repo_url"`
	BaseRef       string `json:"base_ref"`
	Branch        string `json:"branch,omitempty"` // empty until the task has a result branch
	// LatestJobID is the task's newest job of any kind; 0 before the
	// first one was queued.
	LatestJobID int64 `json:"latest_job_id,omitempty"`
}

type TaskInstructions struct {
	Worker   RoleSnapshot `json:"worker"`
	Reviewer RoleSnapshot `json:"reviewer"`
	Skills   []TaskSkill  `json:"skills,omitempty"`
	// SkillsDir is the project's effective skills_dir when the task was
	// resolved; the directory line of every prompt of the task names it.
	SkillsDir string `json:"skills_dir,omitempty"`
}

type TaskLandInfo struct {
	ID    int64  `json:"id"`
	Title string `json:"title"`
	Class string `json:"class"`
	State string `json:"state"`
	Spec  string `json:"spec"`
	// Deps are the ids of the tasks this one depends on (§6.1).
	Deps []int64 `json:"deps,omitempty"`
	// Approved: the task is done and its last review, after its last
	// author job, was a substantive approve (§7).
	Approved bool `json:"approved"`
	// ApprovedHead is the pushed head the approving review saw, as the
	// author job's result recorded it; empty when it recorded none, and
	// land then warns instead of refusing (§7.1).
	ApprovedHead string `json:"approved_head,omitempty"`
	// Summary is the worker's summary (§5.4) from the task's last author
	// job: model output, data only.
	Summary string `json:"summary,omitempty"`
	// CommitMessage is the commit message (§5.4) the task's last author
	// job's worker wrote for the land job (§7.1): subject and body in the
	// repo's own style, model output, data only. Empty when the worker
	// gave none, and land then builds the message itself.
	CommitMessage string `json:"commit_message,omitempty"`
	// Family and Model are the authoring agent's, from the job record
	// (§7); empty when the job has no agent or the agent is gone.
	Family string `json:"family,omitempty"`
	Model  string `json:"model,omitempty"`
}

type TaskParams struct {
	RepoURL  string
	BaseRef  string
	Title    string
	Spec     string
	CheckCmd string // ” = no check
	Class    string // ” = implement
	// Harness and Labels are the queued job's placement constraints
	// (§8): the harness that must run it and the labels a runner must
	// offer in full.
	Harness string
	Labels  []string
	// Skills names, in order, the project's imported skills the task's
	// prompts carry (§5.10): resolved and copied onto the task once, at
	// creation; nil or empty = none.
	Skills []string
}

type TaskResult struct {
	Answer    Answer
	ProjectID int64
	TaskID    int64
	JobID     int64
	Run       int
}

type TaskSkill struct {
	Name   string `json:"name"`
	For    string `json:"for"`
	Text   string `json:"text"`
	Digest string `json:"digest"`
	// Description is the skill's frontmatter line, recorded beside the
	// text so a plan review can judge the pick without the store.
	Description string `json:"description,omitempty"`
	TreeDigest  string `json:"tree_digest,omitempty"`
}

type WakeBudgetInfo struct {
	ProjectID int64  `json:"project_id"`
	RepoURL   string `json:"repo_url"`
	Budget    int    `json:"budget"`
	Wakes     int    `json:"wakes"`
	ResetsAt  string `json:"resets_at"`
	Waiting   int    `json:"waiting"`
	// Default says no per-project setting stands: the engine's default
	// (the config file's foreman_wakes_per_day, else the built-in 20)
	// is the budget in effect.
	Default bool `json:"default"`
}

type WakeOutcome string