fleet

type Checkin struct {
	Fleet   string
	BoardID string
	Member  Member // a copy, status included
	Reason  string // the member's health, or "scheduled" under PolicyAlways
	Missed  int    // unanswered check-ins before this one
}

type Fleet struct {
	Name       string `json:"name"`
	BoardID    string `json:"board_id"`
	Tab        string `json:"tab,omitempty"`
	Source     string `json:"source,omitempty"` // the epic doc it was cut from
	RoadmapDir string `json:"roadmap_dir,omitempty"`
	State      string `json:"state"`
	Created    int64  `json:"created,omitempty"` // unix millis, stamped by the caller

	// Watch is the fleet's check-in policy (design 054); nil means the
	// defaults (smart, every 10 minutes, stalled after 5).
	Watch *Watch `json:"watch,omitempty"`

	// Goal is what the whole fleet is for (design 055); nil means none set.
	Goal *Goal `json:"goal,omitempty"`
	// GoalExec configures the fleet's goal executor; nil means the defaults
	// (adaptive, every 5 to 30 minutes).
	GoalExec *GoalExec `json:"goal_exec,omitempty"`
	// GoalStatus is the executor's latest verdict (written by it only).
	GoalStatus *GoalStatus `json:"goal_status,omitempty"`

	Members []Member `json:"members"`
}

type Goal struct {
	Text     string `json:"text"`
	DoneWhen string `json:"done_when,omitempty"` // the acceptance line: how anyone can tell it is met
	DueAt    int64  `json:"due_at,omitempty"`    // unix millis; 0 = no deadline
	State    string `json:"state,omitempty"`     // open (default) | met | dropped
	SetBy    string `json:"set_by,omitempty"`    // pane id, or "human"
	SetAt    int64  `json:"set_at,omitempty"`
	MetAt    int64  `json:"met_at,omitempty"`
	Note     string `json:"note,omitempty"`
}

type GoalExec struct {
	Mode   string `json:"mode,omitempty"`
	MinSec int    `json:"min_sec,omitempty"`
	MaxSec int    `json:"max_sec,omitempty"`
}

type GoalStatus struct {
	State      string   `json:"state"`
	Pct        int      `json:"pct"`                 // -1 unknown
	FinishAt   int64    `json:"finish_at,omitempty"` // critical-path finish; 0 unknown
	Unknown    int      `json:"unknown,omitempty"`   // open paths with no estimate
	Bottleneck string   `json:"bottleneck,omitempty"`
	Waiting    int      `json:"waiting,omitempty"`
	Summary    string   `json:"summary,omitempty"` // the report's first line
	Why        []string `json:"why,omitempty"`
	AssessedAt int64    `json:"assessed_at"`
	NextAt     int64    `json:"next_at,omitempty"`
	Sent       int      `json:"sent,omitempty"` // directives sent in that cycle
	// Members is the primary condition per member pane id.
	Members map[string]string `json:"members,omitempty"`
}

type GoalUpdate struct {
	// Member selects a member (pane id, prefix, label); empty means the
	// fleet's own goal.
	Member   string `json:"member,omitempty"`
	Text     string `json:"text,omitempty"`
	DoneWhen string `json:"done_when,omitempty"`
	DueSec   int    `json:"due_sec,omitempty"` // seconds from now; 0 keeps the due time (or none)
	// State: "" sets the goal (Text required); met / dropped closes it.
	State string `json:"state,omitempty"`
	Note  string `json:"note,omitempty"`
	SetBy string `json:"set_by,omitempty"`
}

type HealthChange struct {
	Fleet  string
	Member Member // a copy, status included
	From   string
	To     string
	// Cycle is set on a deadlock: the pane ids in the cycle, in order.
	Cycle []string
}

type KV interface {
	Put(key string, value []byte) (uint64, error)
	Get(key string) (nats.KeyValueEntry, error)
	Delete(key string, opts ...nats.DeleteOpt) error
	Keys(opts ...nats.WatchOpt) ([]string, error)
}

type LivePanesFunc func() (map[string]bool, error)

type Member struct {
	PaneID    string `json:"pane_id"`
	Label     string `json:"label,omitempty"`
	Role      string `json:"role,omitempty"`
	Unit      string `json:"unit,omitempty"`
	Parent    string `json:"parent,omitempty"` // parent's pane id
	Worktree  string `json:"worktree,omitempty"`
	SessionID string `json:"session_id,omitempty"` // resumable with `claude -r`

	// Status is the member's row in the status ledger (design 054): declared
	// work, observed activity, derived health. Owned by the fleet actor; a
	// membership upsert that carries none keeps the one already recorded.
	Status *MemberStatus `json:"status,omitempty"`

	// Goal is this agent's individual goal (design 055). Kept across a
	// membership upsert that carries none, like Status.
	Goal *Goal `json:"goal,omitempty"`
}

type MemberStatus struct {
	// Declared.
	Work      string   `json:"work,omitempty"`
	Task      string   `json:"task,omitempty"`
	Note      string   `json:"note,omitempty"`
	BlockedBy []string `json:"blocked_by,omitempty"` // member pane ids, "human", or "ext:<what>"
	UpdatedAt int64    `json:"updated_at,omitempty"` // last declaration
	WorkSince int64    `json:"work_since,omitempty"` // when Work last changed

	// Derived from every member's BlockedBy. Never declared.
	BlockerFor []string `json:"blocker_for,omitempty"`

	// Observed.
	Activity   string `json:"activity,omitempty"`
	ActiveAt   int64  `json:"active_at,omitempty"`   // last time seen working
	ObservedAt int64  `json:"observed_at,omitempty"` // last observation
	JoinedAt   int64  `json:"joined_at,omitempty"`   // first time the ledger saw this member

	// Derived.
	Health      string `json:"health,omitempty"`
	HealthSince int64  `json:"health_since,omitempty"`

	// Check-in bookkeeping.
	CheckinAt     int64  `json:"checkin_at,omitempty"`     // last check-in sent
	CheckinCmd    string `json:"checkin_cmd,omitempty"`    // that check-in's cmd id, until answered
	CheckinMissed int    `json:"checkin_missed,omitempty"` // consecutive unanswered

	// Progress toward the CURRENT task (design 055), declared with
	// `--pct` / `--eta`. A new task text resets both: they described the old
	// one. Pct is a pointer because 0% is a real answer and "never said" is
	// a different one.
	Pct      *int  `json:"pct,omitempty"`
	EtaAt    int64 `json:"eta_at,omitempty"`     // unix millis the agent expects to finish
	EtaSetAt int64 `json:"eta_set_at,omitempty"` // when that estimate was given

	// The goal executor's pending ask (HURRY / REALIGN): answered, like a
	// check-in, by the member's next declaration.
	GoalAskAt  int64  `json:"goal_ask_at,omitempty"`
	GoalAskCmd string `json:"goal_ask_cmd,omitempty"`

	// The status scout (design 056): who made the last declaration ("" the
	// agent, "scout"), and the verdict the scout last answered — it answers
	// a verdict once; if it stands, the agent is asked.
	DeclaredBy  string `json:"declared_by,omitempty"`
	ScoutAt     int64  `json:"scout_at,omitempty"`
	ScoutHealth string `json:"scout_health,omitempty"`
}

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

type Query struct {
	// Name selects one fleet. Empty means every fleet.
	Name string `json:"name,omitempty"`
}

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

type Reply struct {
	Fleets []Fleet `json:"fleets"`

	// ReconciledAt is when membership was last checked against the panes that
	// actually exist, in unix millis; 0 means never.
	//
	// IT IS REPORTED RATHER THAN HIDDEN because the answer is served from the
	// actor's cache and is therefore as old as the last reconcile. That is a
	// deliberate design constraint, not an oversight — see ServeQueries — and a
	// caller that cannot tell a fresh roster from a stale one would eventually
	// act on a member that closed ten minutes ago. Same discipline as the
	// board's RosterReconciled.
	ReconciledAt int64 `json:"reconciled_at,omitempty"`

	// Err carries a refusal. A registry that cannot answer says so; it never
	// answers with an empty list.
	Err string `json:"err,omitempty"`
}

type ScoutAnswer struct {
	Answerable bool     `json:"answerable"`
	Work       string   `json:"work"`
	Task       string   `json:"task"`
	BlockedBy  []string `json:"blocked_by"`
	Note       string   `json:"note"`
	Confidence float64  `json:"confidence"`
	Reason     string   `json:"reason"`
}

type StatusResult struct {
	Fleet  string
	Member *Member // a copy, as stored
	// AnsweredCheckin is the watch's check-in this declaration answered.
	AnsweredCheckin string
	// AnsweredGoalAsk is the goal executor's ask it answered.
	AnsweredGoalAsk string
}

type StatusUpdate struct {
	Work      string   `json:"work"`
	Task      string   `json:"task,omitempty"`
	Note      string   `json:"note,omitempty"`
	BlockedBy []string `json:"blocked_by,omitempty"` // refs: pane id, id prefix, label, "human", "ext:<what>"
	// KeepTask leaves Task as it was when Task is empty, so `status blocked
	// --blocked-by mgr` does not erase what the agent is blocked ON.
	KeepTask bool `json:"keep_task,omitempty"`

	// Pct (0–100) and EtaSec (seconds from now) are progress toward the
	// task (design 055). Optional; nil / 0 leave what was declared before,
	// unless the task text changes.
	Pct    *int `json:"pct,omitempty"`
	EtaSec int  `json:"eta_sec,omitempty"`

	// By is who declares: "" the agent itself, "scout" the status scout on
	// its behalf (design 056). A scout's declaration answers nothing that was
	// asked of the agent: its pending check-in and the executor's ask stay
	// pending, so an agent never loses a question it was meant to answer.
	By string `json:"by,omitempty"`
}

type Update struct {
	Op string `json:"op"`

	Fleet  Fleet  `json:"fleet,omitempty"`  // OpRegister
	Name   string `json:"name,omitempty"`   // every other op
	State  string `json:"state,omitempty"`  // OpState
	Member Member `json:"member,omitempty"` // OpMemberUpsert
	PaneID string `json:"pane_id,omitempty"`

	Status   StatusUpdate `json:"status,omitempty"`    // OpStatus
	Watch    Watch        `json:"watch,omitempty"`     // OpWatch
	Goal     GoalUpdate   `json:"goal,omitempty"`      // OpGoal
	GoalExec GoalExec     `json:"goal_exec,omitempty"` // OpGoalExec
	// contains filtered or unexported fields
}

type UpdateReply struct {
	OK    bool   `json:"ok"`
	Fleet *Fleet `json:"fleet,omitempty"`
	// Member is the member as stored after an OpStatus.
	Member *Member `json:"member,omitempty"`
	// AnsweredCheckin is the check-in cmd an OpStatus answered, if any.
	AnsweredCheckin string `json:"answered_checkin,omitempty"`
	// AnsweredGoalAsk is the goal executor's ask an OpStatus answered.
	AnsweredGoalAsk string `json:"answered_goal_ask,omitempty"`
	Err             string `json:"err,omitempty"`
}

type Watch struct {
	Policy      string `json:"policy,omitempty"`
	IntervalSec int    `json:"interval_sec,omitempty"`
	StallSec    int    `json:"stall_sec,omitempty"`
	// Answer is who answers a status check-in: "agent" (default) or
	// "scout" — a cheap model reads the agent's screen and posts and answers
	// for it, and the agent is asked only when it cannot tell (design 056).
	Answer string `json:"answer,omitempty"`
	// ScoutModel is the scout's model (claude CLI name or alias); default haiku.
	ScoutModel string `json:"scout_model,omitempty"`
}