runner

type CheckResult struct {
	ExitCode int    `json:"exit_code"`
	TimedOut bool   `json:"timed_out"`
	Output   string `json:"output_tail"`
	// Log is the whole captured output, for the check log artifact (§9);
	// the tail above is what the result carries.
	Log string `json:"-"`
}

type ClassCaps struct {
	ToolCap time.Duration
	TimeCap time.Duration
}

type Clock struct {
	// Now reports the current time; every timestamp the run keeps —
	// the activity clock, the stall checks — comes from here.
	Now func() time.Time
	// NewTicker is time.NewTicker behind the Ticker interface, so a
	// manual clock can fire the beats itself.
	NewTicker func(d time.Duration) Ticker
}

type Config struct {
	// Socket is the engine API's Unix socket path (§12.1).
	Socket string
	// Token is the runner token's secret; its name is the runner's
	// identity (§12.3).
	Token string
	// StateDir holds the runner's workspace: the per-repo mirror cache
	// under mirrors/, the per-task worktrees under worktrees/ and the
	// run records (transcripts, check logs) under records/.
	StateDir string
	// Agents is the runner's advertisement (§5.1): one entry per
	// (adapter, harness, model) it offers, persisted by register.
	Agents []api.Agent
	// AgentSpecs records the local launch configuration for init comparisons,
	// including agent-file, which is not part of the engine advertisement.
	AgentSpecs []string
	// Adapters are the adapter implementations the runner can drive;
	// each agent's Adapter names one of them.
	Adapters []adapter.Adapter
	// Labels are offered on every lease poll (§8). The git label is
	// added by defaults when absent (§7.1), so a land job — which needs
	// no agent, only the git label — can always be leased.
	Labels []string
	// MaxParallel is the runner's own cap on parallel jobs (§8.1),
	// advertised at register; 0 means unset.
	MaxParallel int
	// HeartbeatEvery, LeaseWait and CheckTimeout override the defaults;
	// zero keeps them.
	HeartbeatEvery time.Duration
	LeaseWait      time.Duration
	CheckTimeout   time.Duration
	// BackoffMin and BackoffMax bound the wait between lease attempts
	// after a failure; zero keeps leaseBackoffMin and leaseBackoffMax.
	// A test shortens them so a burst of transient failures on a loaded
	// host costs milliseconds, not the minute the defaults add up to.
	BackoffMin time.Duration
	BackoffMax time.Duration
	// SetupTimeout, when set, replaces the time bound a task's recorded
	// setup carries (§5.7); zero keeps the recorded one.
	SetupTimeout time.Duration
	// StallAfter is how long without any worker activity a run counts
	// as stalled (§5.6); zero keeps the 10-minute default, negative
	// turns the silence watch off.
	StallAfter time.Duration
	// ClassCaps overrides the per-class caps (§5.6), keyed by job kind
	// — work, fix, review, foreman. A zero entry keeps that class's
	// default, a set field overrides it, a negative one switches that
	// bound off for the class.
	ClassCaps map[string]ClassCaps
	// KillGrace is how long a stopped worker's process tree has between
	// the runner's SIGTERM and its SIGKILL (§5.6); zero keeps 10 s.
	KillGrace time.Duration
	// ProbeEvery is how often the runner asks the engine for due
	// broken-agent probes (§8 "Health"); zero keeps 1 minute.
	ProbeEvery time.Duration
	// Clock is the runner's time (§5.6): the wall the activity clock
	// reads and the tickers the heartbeats beat on. Nil is real time;
	// tests inject a manual one so no test sleeps minutes.
	Clock Clock
	// GitEnv is extra environment for the runner's own git commands —
	// where its credentials ride when they come from config (§5.1).
	// They never reach the worker's argv or prompt, and the variables they
	// name are stripped from a worker's, a setup command's and a check's
	// environment. The ambient credentials of scrub.go go whether or not
	// this is set; the command line leaves it empty.
	GitEnv []string
	// HarnessEnv is resolved environment per harness, "VAR=value" entries
	// (§5.1): a job's worker gets the entries of its own harness and no
	// other's. It is never logged, stored or put in an error.
	HarnessEnv map[string][]string
	// Ready, when set, runs once the runner holds its state directory's
	// lock and its configuration has passed — the moment it is up. The
	// caller's startup line belongs here: printed before Run, a second
	// process on the same state directory would announce itself up and
	// then be refused at the lock.
	Ready func()
	// Log is the runner's logger; nil uses the default.
	Log *slog.Logger
}

type Ticker interface {
	Chan() <-chan time.Time
	Stop()
}

type WorkerResult struct {
	Status   string `json:"status"`
	Summary  string `json:"summary,omitempty"`
	Question string `json:"question,omitempty"`
	Branch   string `json:"branch,omitempty"`
	Reason   string `json:"reason,omitempty"`
	// Discoveries is what the worker learned that matters beyond its own
	// task (§5.4); the runner keeps it so the engine can hand it to the
	// foreman (§4.2).
	Discoveries string `json:"discoveries,omitempty"`
	// CommitMessage is the commit message the worker wrote for the land
	// job (§5.4): subject and body in the repo's own style, which the
	// worker reads from the project's instructions and the log. The land
	// job uses it when it is there and falls back to its own format when
	// it is not (§7.1); the runner passes it on untouched.
	CommitMessage string `json:"commit_message,omitempty"`
	// Progress is the last progress events, attached when the runner
	// ends a stalled or time-capped run (§5.6) so what the worker was
	// doing rides with the outcome. A worker's own block never carries
	// it.
	Progress []string `json:"progress,omitempty"`
	// ExtraRepos is the commit each extra repository resolved to (§5.8),
	// by name, so the history shows what the job saw. The runner sets it;
	// a worker's own block never carries it.
	ExtraRepos map[string]string `json:"extra_repos,omitempty"`
	// Head is the commit the runner pushed as the task's branch (§7), so
	// a later re-review can ask for the fix round's diff alone. The
	// runner sets it; a worker's own block never carries it.
	Head string `json:"head,omitempty"`
	// ChangedPaths is the task's real changed paths, base...branch
	// (§6.3, §7.1): what the land gate's protected-path rule matches,
	// recorded with the work job's result. The runner sets it; a
	// worker's own block never carries it.
	ChangedPaths []string `json:"changed_paths,omitempty"`
}