hostpoller

type Agent interface {
	// Done is closed when the process exits.
	Done() <-chan struct{}
	// ExitDetail describes how it exited, once Done is closed.
	ExitDetail() string
	// PID is its process id (0 when unknown).
	PID() int
}

type AgentRecord struct {
	Worktree string `json:"worktree"`
	PID      int    `json:"pid"`
	// Start is the launch's kernel start time, observed while it ran (empty
	// when not observed): with PID, its launch identity, so a restarted
	// poller can tell this launch from another at the same pid (cli#1582).
	Start string `json:"start,omitempty"`
}

type BatchSource interface {
	Batches(ctx context.Context) ([]delivery.Batch, error)
}

type Config struct {
	// Capabilities is an explicit full declaration at every refresh, never inferred.
	Capabilities []string `yaml:"capabilities"`
	// Server is the Hadron server URL; empty means the CLI's usual resolution.
	Server string `yaml:"server"`
	// App is the team App the host serves (hrn:app:<root>:<slug>, or an id).
	App string `yaml:"app"`
	// Label names the host to people; empty means the hostname.
	Label string `yaml:"label"`
	// PollIntervalSeconds is how often the host checks in (1 to 86400).
	PollIntervalSeconds int `yaml:"poll_interval_seconds"`
	// KeyFile holds the App key carrying host:operate for this host
	// (required; mode 0600 or tighter). Relative paths resolve against the
	// configuration's directory.
	KeyFile string `yaml:"key_file"`
	// WorktreesRoot is the directory every worktree name token is relative to.
	WorktreesRoot string `yaml:"worktrees_root"`
	// StateFile records the worktrees this poller created and any it must
	// keep. Empty means hadron-host-state.json beside the config.
	StateFile string `yaml:"state_file"`
	// Repos maps a repo token (as worktree.create names it, e.g.
	// hadron-memory/hadron-cli) to the local clone worktrees are added from.
	Repos map[string]string `yaml:"repos"`
	// Workers maps a worker reference (its name in the App, URN or id) to
	// how this host runs it.
	Workers map[string]WorkerConfig `yaml:"workers"`
	// Delivery turns on chat delivery into this host's Orca terminals
	// (cli#907). Absent, the poller carries out host operations only.
	Delivery DeliveryConfig `yaml:"delivery"`
}

type ContextReset struct {
	ID          string
	Epoch       int
	Phase       string
	Reason      string
	WorkerID    string
	SessionID   string
	TaskID      string
	StopGranted bool
	StopLeaseMs int
	// CheckpointNode is the v2 URN of the checkpoint node registered for
	// the relaunch (hadron-server#3300); empty before registration.
	CheckpointNode string
}

type Deliverer interface {
	Deliver(ctx context.Context, b delivery.Batch, r delivery.Recipient) delivery.Outcome
}

type DeliveryConfig struct {
	// Enabled turns delivery on. The host key then also needs
	// attention:deliver; without it delivery switches off for the run.
	Enabled bool `yaml:"enabled"`
	// AckMixed asserts that the server carries A-prime (#2072): mixed wake
	// acknowledgment records ticks/tasks without advancing any chat mark.
	AckMixed bool `yaml:"ack_mixed"`
	// OrcaBin is the absolute path of the orca CLI.
	OrcaBin string `yaml:"orca_bin"`
}

type Event struct {
	Time      time.Time
	Kind      string
	Operation string
	Type      string
	Outcome   string
	Detail    string
}

type ExecHost struct {
	// PromptTimeout bounds worker.end's prompt command.
	PromptTimeout time.Duration
}

type GitTreeState struct {
	// InGit: `git -C <dir> rev-parse --is-inside-work-tree` printed true.
	InGit bool
	// The rest is read only when InGit.
	Dirty    bool
	Upstream string
	Ahead    int
}

type Host interface {
	// CreateWorktree adds a worktree at path on a new branch from base.
	CreateWorktree(ctx context.Context, repoPath, path, branch, base string) error
	// Inspect reads a worktree's state; Exists is false for a missing path.
	Inspect(ctx context.Context, path string) (WorktreeState, error)
	// RemoveWorktree removes a clean worktree.
	RemoveWorktree(ctx context.Context, path string) error
	// Launch starts an agent and returns at once; the agent keeps running.
	Launch(ctx context.Context, spec LaunchSpec) (Agent, error)
	// Prompt runs a short command (worker.end's prompt) to completion.
	Prompt(ctx context.Context, argv []string, dir string, env []string) error
	// Occupied names a process (other than the poller) working inside path,
	// or "" when none is seen. Where the host cannot tell (no /proc), it
	// reports none, and worktree.remove leans on the recorded agents alone.
	Occupied(ctx context.Context, path string) (string, error)
	// Alive reports whether a process id is still running.
	Alive(pid int) bool
}

type LaunchSpec struct {
	Argv []string
	Dir  string
	Env  []string
}

type LinuxProcessControl struct{}

type Operation struct {
	ID            string
	Type          string
	Args          map[string]any
	WorkerID      string
	Status        string
	Result        map[string]any
	FailureReason string
	// LaunchGrant is set only on a collected worker.start.
	LaunchGrant string
}

type Poller struct {

	// BindPoll is how often a pending start asks whether its session bound.
	BindPoll time.Duration
	// Fatal, when set, decides that a failed check-in ends Run: a refused or
	// revoked host key does not heal by retrying, and looping on it would
	// hide it.
	Fatal func(error) bool

	// DeliveryStep, when set, is told how each delivery step's batch read
	// went (delivery.StepRead, StepReadFailed, StepOffByScope).
	DeliveryStep func(at time.Time, read string)
	// WakeStep, when set, is told how each step's wake read went (cli#906
	// row 1).
	WakeStep func(delivery.WakeRead)
	// contains filtered or unexported fields
}

type ProcessControl interface {
	Observe(pid int) (ProcessHandle, error)
	Now() (time.Duration, error)
}

type ProcessHandle interface {
	Identity() ProcessIdentity
	// SignalWithin sends sig only if now() - t0 < lease, with the check and
	// the send adjacent. t0 is read BEFORE the authorizeStop request goes
	// out, so a slow answer shortens the window and never lengthens it. It
	// re-reads the clock after the send and returns how far past the lease
	// the send landed (0 when inside): a late stop the caller records
	// (ruling 0087 A). ErrLeaseExpired means nothing was sent; so does
	// ErrClock, when the check's reading failed or is before t0. A failed
	// reading after the send cannot unsend: the stop stands and late is 0,
	// the check before it having passed on a real reading.
	SignalWithin(sig syscall.Signal, t0, lease time.Duration, now func() (time.Duration, error)) (late time.Duration, err error)
	Close()
}

type ProcessIdentity struct {
	PID       int    `json:"pid"`
	StartTime string `json:"startTime"`
}

type RegisteredHost struct {
	HostID  string
	Workers []RegisteredHostWorker
}

type RegisteredHostWorker struct {
	WorkerID string
	URN      string
	Name     string
}

type RegisteredWorker struct {
	Worker    string // the configured reference
	Family    string
	Worktrees []string
}

type Registration struct {
	Capabilities        []string
	Label               string
	PollIntervalSeconds int
	Workers             []RegisteredWorker
}

type ResetCheckpoint struct {
	Title   string
	Content string
}

type ResetDeps struct {
	// Proc observes and signals agent processes (LinuxProcessControl).
	Proc ProcessControl
	// Git is the Git determination (GitTree).
	Git func(ctx context.Context, dir string) (GitTreeState, error)
	// Idle proves the worker's agent idle with an empty composer and no
	// menu (BUSY, DRAFT_OR_MENU). Nil means this host cannot prove it, and
	// every reset refuses NOT_IDLE: idle is never assumed.
	Idle func(ctx context.Context, workerRef string) error
}

type ResetRecord struct {
	ResetID     string `json:"resetId"`
	OperationID string `json:"operationId"`
	WorkerID    string `json:"workerId"`
	// Epoch is the last epoch a step returned (0 before the claim).
	Epoch int `json:"epoch"`
	// Old is the agent process observed before the claim; New is the
	// relaunched one, once started.
	Old ProcessIdentity  `json:"old"`
	New *ProcessIdentity `json:"new,omitempty"`
	// Checkpoint is the checkpoint node the recovery was registered with,
	// handed to the relaunched agent; empty until registerRecovery.
	Checkpoint string `json:"checkpoint,omitempty"`
	// Relaunching is set on disk before the relaunch starts an agent, so a
	// restart in between never starts a second one.
	Relaunching bool `json:"relaunching,omitempty"`
	// LateStopMs is how far past its lease the stop landed, written as
	// soon as the signal returns, so the late-stop event survives an agent
	// that does not exit, a cancellation and a restart (cor:agt:050:27
	// part 10). 0 when on time or not yet sent.
	LateStopMs int64 `json:"lateStopMs,omitempty"`
}

type ResetServer interface {
	ClaimReset(ctx context.Context, resetID string, epoch int, p ProcessIdentity) (ResetStep, error)
	// RegisterResetRecovery writes the checkpoint with the host key and
	// registers it (#3276, ruling 0090 A): the host never names a node.
	RegisterResetRecovery(ctx context.Context, resetID string, epoch int, cp ResetCheckpoint, sessionID, taskID string) (ResetStep, error)
	AuthorizeResetStop(ctx context.Context, resetID string, epoch int, p ProcessIdentity) (ResetStep, error)
	// late is how long after its lease the stop signal landed (0 when on
	// time; procctl SignalWithin's result); it is sent as lateStopMs.
	ReportResetAgentStopped(ctx context.Context, resetID string, epoch int, late time.Duration) (ResetStep, error)
	ReportResetRelaunched(ctx context.Context, resetID string, epoch int, p ProcessIdentity) (ResetStep, error)
	ReportResetRelaunchFailed(ctx context.Context, resetID string, epoch int, reason string) (ResetStep, error)
	// ReadReset reads one reset this host collected (#3273), for restart
	// recovery; it changes nothing.
	ReadReset(ctx context.Context, resetID string) (ContextReset, error)
}

type ResetStep struct {
	Refused  string
	Replayed bool
	Reset    ContextReset
}

type ResetStepError struct {
	Code string
	Err  error
}

type Server interface {
	Register(ctx context.Context, r Registration) (RegisteredHost, error)
	Collect(ctx context.Context) ([]Operation, error)
	// Report returns the operation as the server recorded it.
	Report(ctx context.Context, id, outcome, worktree, reason string) (Operation, error)
}

type State struct {

	// Created maps a configured worker reference to the worktree tokens this
	// poller created for it.
	Created map[string][]string `json:"created"`
	// Keep maps a worktree token to why it must not be removed.
	Keep map[string]string `json:"keep"`
	// HostID is the id the server derived from the host key at the last
	// registration — how `status` finds this host's own registration, since
	// a label is not unique.
	HostID string `json:"hostId"`
	// Agents are the agents this poller launched, by worker id: the
	// worktree each runs in and its process id. A launched agent outlives a
	// poller restart (it runs in its own session), so the in-memory record
	// alone would forget it and let worktree.remove take a tree from under
	// a live agent. A reused pid only makes a check refuse: the safe way.
	Agents map[string]AgentRecord `json:"agents"`
	// Resets are the worker.reset-context operations this poller collected
	// and has not finished reporting, by reset id (#1043). Written before
	// the claim, so a restarted poller knows which resets to read; it never
	// stores a phase, which recovery always reads from the server.
	Resets map[string]ResetRecord `json:"resets,omitempty"`
	// contains filtered or unexported fields
}

type WakeDeliverer interface {
	DeliverWake(ctx context.Context, w delivery.Wake, r delivery.Recipient) delivery.Outcome
}

type WakePage struct {
	Wakes []delivery.Wake
	// BudgetExhausted: WAKE_BUDGET_EXHAUSTED. Nothing is typed; the
	// withheld wakes stay due.
	BudgetExhausted bool
	// Dormant and Withheld are counted in status only.
	Dormant, Withheld int
}

type WakeSource interface {
	Wakes(ctx context.Context) (WakePage, error)
}

type WorkerConfig struct {
	// Family is the model family it runs as here, e.g. claude or codex.
	Family string `yaml:"family"`
	// Launch is the argv that starts its agent in a worktree. The poller adds
	// HADRON_LAUNCH_GRANT to its environment and nothing else of Hadron's.
	Launch []string `yaml:"launch"`
	// End is an optional argv that prompts the running agent to end its own
	// session with a handoff (worker.end). It is never a kill.
	End []string `yaml:"end"`
	// EndWait bounds how long worker.end waits for the session to end
	// (default 15m).
	EndWait string `yaml:"end_wait"`
	// Recover is an optional argv that hands a relaunched agent its recovery
	// prompt after a worker.reset-context (#1043), the way End prompts an
	// end. It gets HADRON_SESSION_ID, HADRON_WORKER_ID and
	// HADRON_RECOVERY_NODE (the checkpoint node's reference): ids only. A
	// worker without it is never reset on this host.
	Recover []string `yaml:"recover"`
	// Worktrees are this worker's existing worktree name tokens, relative to
	// worktrees_root, beyond the ones this poller created.
	Worktrees []string `yaml:"worktrees"`
	// TUI is the agent interface its terminal shows, claude or codex, when
	// the model family does not say (a glm worker runs in Claude Code).
	// Delivery holds a terminal that shows anything else.
	TUI string `yaml:"tui"`
}

type WorktreeState struct {
	Exists bool
	// IsWorktree is false for a path that exists but is not a git worktree.
	IsWorktree bool
	Branch     string
	// Dirty is uncommitted or untracked changes.
	Dirty bool
	// Upstream is the branch's upstream, empty when it has none.
	Upstream string
	// Ahead counts commits not on the upstream.
	Ahead int
}