lifecycle

type Config struct {
	StateDir  string
	StorePath string
	Socket    string
	LockPath  string
	TokenFile string

	// Idle is how long with no live jobs and no connected requests the
	// engine tolerates before it exits (§13); zero keeps 30 minutes.
	Idle time.Duration
	// Caps are the concurrency caps and cost weights the config file
	// named (§8.1); the zero value caps nothing.
	Caps caps.Limits
	// Notify selects the local notifier (§10): notify.ModeAuto picks
	// the OS tool on PATH, notify.ModeNone silences notifications; the
	// empty value keeps auto.
	Notify string
	// NotifyWebhook is the optional webhook URL (§10): one JSON POST
	// per delivered notification, beside the OS banner. Empty = none.
	// The URL may carry a token, so it is never logged and never
	// reaches the status or the history.
	NotifyWebhook string
	// SnapshotDir is where the engine snapshots its store daily (§6.4);
	// empty takes no snapshots.
	SnapshotDir string
	// Rounds are the config file's default round caps; unnamed keys keep
	// the engine defaults.
	Rounds RoundsConfig
	// Review is the config file's default tier, effort and family rule of
	// a review; unnamed keys keep the engine defaults.
	Review engine.ReviewConfig
	// TaskAutoRetry controls transient work retries; nil keeps the default, on.
	TaskAutoRetry *bool
	// ForemanWakeBudget is the default daily foreman wake budget of every
	// project (§4.3); 0 keeps the built-in default of 20. A project's
	// foreman_wakes_per_day setting overrides it.
	ForemanWakeBudget int
	// DefaultReviewer is the harness a standalone review goes to when its
	// author's family cannot be told; empty = none.
	DefaultReviewer string
	// IdleTick is how often busyness is checked; zero derives a tick
	// from Idle, clamped to [200ms, 30s].
	IdleTick time.Duration
	// Now is the idle rule's clock; tests inject one and drive it. Nil
	// is real time.
	Now func() time.Time
	// FlushNotifications is the §10 hook, called once before an idle
	// exit with unsent notifications to deliver; nil is "nothing to
	// flush yet".
	FlushNotifications func(ctx context.Context) error
	// FlushGrace bounds every shutdown wait on the notification flush
	// and on a delivery still in flight (§13): past it the engine
	// leaves without the wait, with a log line. Zero keeps 10s.
	FlushGrace time.Duration
	// Notifier overrides the notifier the notify mode resolves (§10):
	// the tests inject one; production leaves it nil.
	Notifier notify.Notifier
	// Log is the engine's logger; nil uses slog's default.
	Log *slog.Logger
}

type FileConfig struct {
	StateDir    string
	IdleMinutes float64 // 0 = the default
	Notify      string  // notify = auto|none (§10); empty = auto
	// NotifyWebhook is the optional webhook URL (notify.webhook, §10):
	// one JSON POST per delivered notification. Empty = none. The URL
	// may carry a token, so it lives in this file alone — never in a
	// project's own files — and never reaches a log, status or error.
	NotifyWebhook string
	Caps          caps.Limits // concurrency caps, cost weights and tier overrides (§8.1)
	// Rounds are the default per-task round caps (rounds.fix,
	// rounds.review, rounds.restart); a key the file never names stays nil
	// and keeps the engine default.
	Rounds RoundsConfig
	// Review is the default tier, effort and family rule of a review
	// (review.tier, review.effort, review.family, §7, §8); a key the file
	// never names stays empty and keeps the engine default.
	Review engine.ReviewConfig
	// SnapshotDir is where the engine snapshots its store daily (§6.4):
	// an absolute directory outside the state directory's store. Empty =
	// no snapshots.
	SnapshotDir string
	// TaskAutoRetry controls one automatic restart after a transient work
	// failure. Nil keeps the engine default, on.
	TaskAutoRetry *bool
	// ForemanWakesPerDay is the default daily foreman wake budget of
	// every project (§4.3); 0 keeps the built-in default. A project's
	// foreman_wakes_per_day setting overrides it.
	ForemanWakesPerDay int
	// DefaultReviewer is the harness a standalone review (§7) goes to when
	// its author's family cannot be told. Empty = none.
	DefaultReviewer string
	// Tools is the default claude worker tool scope per "harness/model"
	// (§5.2, tools.<harness>/<model>): the parsed patterns, an empty
	// non-nil list for an explicit none. A pair the file never names has
	// no entry, which is the Go default and not none.
	Tools map[string][]string
	// Env holds the references of env.<harness>.<VAR> (§5.1), harness then
	// variable: keychain:<item> or file:<path>. Never a value.
	Env map[string]map[string]string
}

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

type Paths struct {
	StateDir string
	Store    string
	Socket   string
	Lock     string
	Tokens   string
	Log      string
}

type RecoverConfig struct {
	StateDir  string
	StorePath string // zero derives it from StateDir
	LockPath  string // zero derives it from StateDir
	// SnapshotDir is where the engine's snapshots are; empty = none, and
	// the store is rebuilt from plan files alone.
	SnapshotDir string
	// Repos name repositories, beyond the projects the snapshot holds,
	// whose plan files are applied: a project born after the last
	// snapshot, or every project when there is no snapshot.
	Repos []string
	// Now is the clock; nil is real time.
	Now func() time.Time
}

type RecoverReport struct {
	Snapshot   string // the snapshot restored; "" when there was none
	MovedAside string // where the old store file went; "" when there was none
	Plans      []engine.PlanRecovery
	Warnings   []string
	Epoch      int           // the fence epoch after the bump
	Hold       time.Duration // how long dispatch is held after the recovery
}

type RoundsConfig struct {
	Fix, Review, Restart *int
}

type RunnerStartOptions struct {
	StateDir   string
	ConfigPath string
	Binary     string
	Args       []string
	Wait       time.Duration
	// Restart, when "drain" or "now", makes a running runner make way
	// for the start: "drain" hands it a request it honours between
	// jobs — it takes no new lease and exits once its running jobs
	// finish — while "now" has it exit at once, cutting them. Empty
	// keeps a running runner running and only reports it.
	Restart string
}

type RunnerStartResult struct {
	Existing bool
	Record   runnerstate.Record
}

type SecretCommand func(name string, args ...string) ([]byte, error)

type StartOptions struct {
	Socket   string
	StateDir string
	// ConfigPath, when set, is passed to the engine so it reads the same
	// config file the client did.
	ConfigPath string
	// Binary is the brigada to start; empty means this executable.
	Binary string
	// Wait overrides the 5 s health wait; zero keeps it.
	Wait time.Duration
	// Log is where the starter's messages go; nil uses slog's default.
	Log *slog.Logger
}