coordinator

type Coordinator interface {
	Spawn(context.Context, []subagents.Task, string) (*RunHandle, error)
	// SpawnNew is Spawn plus an isNew signal: false when the idempotency-key
	// lookup returned an existing run some other caller started, so a
	// caller can tell whether it is safe to treat itself as the run's sole
	// owner (e.g. before canceling it on its own unrelated context dying).
	SpawnNew(context.Context, []subagents.Task, string) (*RunHandle, bool, error)
	EnsureRun(context.Context, EnsureRunRequest) (*RunHandle, error)
	EnsureSingleTaskRun(context.Context, EnsureRunRequest) (*RunHandle, error)
	EnsureTerminalSingleTaskRun(context.Context, EnsureRunRequest, ledger.TaskStatus) (*RunHandle, error)
	// JoinAsRecovered returns a recovered, wait-only handle for an already
	// admitted run, or ledger.ErrNotFound if none is admitted yet. It never
	// claims to run the child, dispatches its handler, or resumes it as a
	// local actor: Cancel on the returned handle always takes the fail-closed
	// recovered path, which refuses when a task's persisted status looks
	// nonterminal with no verifiable live owner.
	JoinAsRecovered(context.Context, EnsureRunRequest) (*RunHandle, error)
	Inspect(context.Context, *RunHandle) (ledger.RunSnapshot, error)
	Join(context.Context, *RunHandle) (*RunResult, error)
	Cancel(context.Context, *RunHandle) error
	SetTimeSource(func() time.Time)
	WithRetryPolicy(RetryPolicy) Coordinator
	ResumeInterruptedRun(context.Context, string) (*RunHandle, error)
	ListInterruptedRuns(context.Context) ([]RecoveredRun, error)
	SubscribeLifecycle(LifecycleSubscriber) func()
	// PostTaskMessage persists a typed agent message and announces a
	// task_message lifecycle event (ID + synopsis only). Plan 53.01 seam.
	PostTaskMessage(ctx context.Context, runID, taskID string, msg agentmsg.Message) error
	// ParkQuestion / DeliverAnswer / Transition* support plan 53.02 questions.
	// maxWait is the asker's effective max wait; the park expires at
	// max(parkTTL, maxWait+parkSlack) so long waits are never evicted early.
	ParkQuestion(runID, taskID, messageID string, maxWait ...time.Duration) (answerCh <-chan string, unpark func(), err error)
	// DeliverAnswer unblocks a park when inReplyTo matches the parked message id
	// (empty inReplyTo matches any live park for the task).
	DeliverAnswer(runID, taskID, inReplyTo, body string) bool
	TransitionToAwaitingInput(ctx context.Context, runID, taskID string) error
	TransitionFromAwaitingInput(ctx context.Context, runID, taskID, newStatus string) error
	ConsumeMessageQuota(runID, taskID string, max int) error
	// RefundMessageQuota decrements the per-task upstream message count after a
	// failed persist so a failed message never permanently burns a budget slot
	// (messageQuota is otherwise increment-only). Floored at zero: it only ever
	// undoes a prior ConsumeMessageQuota.
	RefundMessageQuota(runID, taskID string)
	CountPendingQuestions(runID, taskID string) int
	// ParkedQuestions returns the live parked questions for a run
	// (TaskID/MessageID/ExpiresAt), read under the question registry lock.
	// Expired parks are treated as absent via the existing eviction.
	ParkedQuestions(runID string) []ParkedQuestion
	ListRunMessages(ctx context.Context, runID, taskID string) ([]MessageSummary, error)
	LoadMessageBody(ctx context.Context, contentRef string) (agentmsg.Message, error)
	// SendToTask enqueues a parent→child message (steer/answer) after ledger persist.
	SendToTask(ctx context.Context, h *RunHandle, taskID string, msg agentmsg.Message) (delivered bool, err error)
	// WithMessagingLimits applies body/mailbox budgets from [subagents.messaging].
	WithMessagingLimits(maxBodyBytes, mailboxCapacity int) Coordinator
	// Ask registry (plan 53.04).
	RegisterAsk(runID, askerTaskID, askerRole, askID string, ancestors []string)
	TryRegisterAsk(runID, askerTaskID, askerRole, askID string, ancestors []string, maxAsks int) bool
	AsksUsedByTask(runID, taskID string) int
	ReferralSpawnsUsed(runID string) int
	IncReferralSpawn(runID string)
	TryIncReferralSpawn(runID string, max int) bool
	DecReferralSpawn(runID string)
	AskLookup(askID string) (askerTaskID string, ok bool)
	AskChainInfo(parentAskID, toRole string) (depth int, cycle bool, ancestors []string)
	CompleteAskAnswer(askID string) error
	ClaimAskAnswer(askID string) (askerTaskID string, err error)
	// BeginAskAnswer claims an open registry ask for parent/peer one-shot.
	// claimed=false,err=nil means not a registry ask (question path).
	BeginAskAnswer(askID string) (askerTaskID string, claimed bool, err error)
	IsAskAnswered(askID string) bool
	CloseAsk(askID string)
	// SealAskAnswer closes open/claimed ask; true only if this call sealed.
	SealAskAnswer(askID string) bool
	UnclaimAskAnswer(askID, askerTaskID string)
	// FindLiveTaskByRole returns a running/awaiting task whose AgentName matches role.
	FindLiveTaskByRole(ctx context.Context, runID, role string) (taskID string, ok bool, err error)
	// HandleForRun returns the in-memory handle for an active run, if any.
	HandleForRun(runID string) *RunHandle
	// MailboxSend delivers an already-persisted message to a task mailbox.
	MailboxSend(h *RunHandle, taskID string, msg agentmsg.Message) (delivered bool, err error)
	// SpawnReferralFromAsk starts a same-run referral task for a non-blocking ask.
	// Optional meta supplies agent digest/provider/model for production agents.
	SpawnReferralFromAsk(ctx context.Context, runID, toRole string, ask agentmsg.Message, meta ...ReferralSpawnMeta) (taskID string, err error)
	// SpawnReferral starts a same-run task by role/name with the given input.
	// askID, when non-empty, is bound before the referral goroutine starts.
	SpawnReferral(ctx context.Context, runID string, task subagents.Task, askID string) (taskID string, err error)
}

type EnsureRunRequest struct {
	RunID          string
	Tasks          []subagents.Task
	IdempotencyKey string
	ForceResume    bool
	// NonInteractiveParent marks the run's parent as a non-interactive
	// controller that can never answer child questions. Parked questions for
	// tasks in such a run are declined immediately at park time so the child
	// proceeds instead of burning its full wait budget. Generic mechanism: the
	// coordinator never assumes who the parent is, only that it cannot answer.
	NonInteractiveParent bool
	Policy               ledger.RunPolicy
}

type LifecycleSubscriber func(event ledger.LifecycleEvent)

type MessageSummary struct {
	MessageID  string        `json:"message_id"`
	Kind       agentmsg.Kind `json:"kind"`
	Synopsis   string        `json:"synopsis"`
	ContentRef string        `json:"content_ref,omitempty"`
	TaskID     string        `json:"task_id,omitempty"`
	Sequence   uint64        `json:"sequence,omitempty"`
}

type ParkedQuestion struct {
	TaskID    string    `json:"task_id"`
	MessageID string    `json:"message_id"`
	ExpiresAt time.Time `json:"expires_at"`
}

type RecoveredRun struct {
	RunID          string `json:"run_id"`
	DisplayName    string `json:"display_name"`
	Status         string `json:"status"`
	WasInterrupted bool   `json:"was_interrupted"`
	// CreatedAt lets a listing show a run's age. Recover classifies a run
	// abandoned days ago identically to one interrupted moments ago, so age is
	// the only thing that distinguishes news from noise.
	CreatedAt time.Time `json:"created_at"`
	// HeldByAnotherExecutor is true when the run has an execution claim held
	// by a different repository instance (i.e. another mivia process). The
	// dashboard shows this separately so users do not try to resume it.
	HeldByAnotherExecutor bool `json:"held_by_another_executor"`
}

type ReferralSpawnMeta struct {
	AgentDigest  string
	ProviderName string
	Model        string
}

type RetryPolicy struct {
	// MaxRetries is the maximum number of retry attempts per task.
	// 0 means no retry (failed/timed_out tasks are terminal).
	MaxRetries int `toml:"max_retries" json:"max_retries"`

	// BaseBackoff is the initial backoff duration before the first retry.
	// Each subsequent retry multiplies by BackoffFactor, capped at MaxBackoff.
	BaseBackoff time.Duration `toml:"base_backoff" json:"base_backoff"`

	// MaxBackoff caps the per-retry backoff duration.
	MaxBackoff time.Duration `toml:"max_backoff" json:"max_backoff"`

	// BackoffFactor is the multiplier applied to backoff after each attempt.
	// Default 2.0 (exponential). A value of 0 is treated as 2.0.
	BackoffFactor float64 `toml:"backoff_factor" json:"backoff_factor"`

	// JitterFraction adds randomisation: each backoff is multiplied by
	// 1 ± JitterFraction/2. E.g. 0.25 means ±12.5%. 0 disables jitter.
	JitterFraction float64 `toml:"jitter_fraction" json:"jitter_fraction"`
}

type RetryState struct {
	TaskID   string
	Attempts int // number of retries already performed
	Policy   RetryPolicy
	// contains filtered or unexported fields
}

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

type RunResult struct {
	Snapshot ledger.RunSnapshot
	Results  []subagents.Result
	Err      error
}

type TaskProgress struct {
	ToolCalls    int       // count of tool-call START events, dropped or not
	LastTool     string    // most recent tool name (start or end)
	LastActivity time.Time // most recent sink event, any kind
}