investigate

type AgentChoice struct {
	Name  string
	Label string
}

type AppendOptions struct {
	AgentName   string
	RunID       string
	Topic       string
	FindingsDoc string
	StateDoc    string
	StartingSHA string
}

type BootstrapInput struct {
	// SeedDoc is the absolute path to a user-provided seed file. Empty
	// when no seed was passed.
	SeedDoc string

	// Topic is the topic-only investigation prompt collected from the
	// spawn-time multipicker (set when neither SeedDoc nor IssueLinkSeed
	// is supplied). Empty otherwise.
	Topic string

	// IssueLinkSeed is the markdown bytes produced by ResolveIssueLink.
	// Empty when --issue-link was not used.
	IssueLinkSeed []byte

	// IssueLinkTopic is the topic derived from the resolved issue/PR
	// title. Used only when IssueLinkSeed is non-empty.
	IssueLinkTopic string

	// FindingsDoc is the absolute path the findings doc must be written
	// to.
	FindingsDoc string
}

type BootstrapResult struct {
	// Topic is the resolved topic — used downstream for slug derivation,
	// manifest entries, and prompt rendering.
	Topic string

	// FindingsDoc is the absolute path the findings doc was written to
	// (echoes BootstrapInput.FindingsDoc).
	FindingsDoc string
}

type CleanDeps struct {
	ManifestStore *LocalManifestStore
	// RunDir returns the per-run directory path for a given run id. In
	// production this is StateStore.RunDir; tests inject a fake.
	RunDir func(runID string) string
	// ManifestPath returns the on-disk path for a manifest. In
	// production this is LocalManifestStore.PathFor(m).
	ManifestPath func(m LocalManifest) string
	// Confirm prompts the user with the given message and returns the
	// y/N answer. Nil → real huh-backed prompt (use newAccessibleForm).
	Confirm func(ctx context.Context, message string) (bool, error)
}

type CleanInput struct {
	// RunID, when non-empty, targets one run via exact-match-then-
	// unique-prefix. Ignored when All is true.
	RunID string

	// All targets every investigation found by the manifest store.
	All bool

	// Force skips the confirmation prompt.
	Force bool

	// Out / ErrOut sink the operator-facing output.
	Out    io.Writer
	ErrOut io.Writer
}

type ComposeInput struct {
	// Topic is the human-readable subject of the investigation. Used in
	// the body of the prompt as plain text — never as a section heading,
	// since the rendered findings doc owns that.
	Topic string

	// AgentName is the agent the prompt is being rendered for (e.g.
	// "claude-code").
	AgentName string

	// Round is the 1-indexed round number in the loop.
	Round int

	// MaxTurns is the per-agent turn budget (the "of N" half of
	// "Round X of N").
	MaxTurns int

	// Turn is the 1-indexed overall turn number across rounds.
	Turn int

	// AlwaysPrompt, if non-empty, is appended verbatim at the end of the
	// rendered prompt. Lets users inject project-specific guardrails into
	// every turn via settings.
	AlwaysPrompt string

	// Files holds the findings + state absolute paths the agent must
	// read and edit.
	Files Files
}

type Deps struct {
	// GetAgentsWithHooksInstalled returns the registry names of all agents
	// whose lifecycle hooks are installed in the current repo.
	GetAgentsWithHooksInstalled func(ctx context.Context) []types.AgentName

	// NewSilentError wraps an error so the cobra root does not double-print
	// it.
	NewSilentError func(err error) error

	// SpawnerFor maps an agent name → Spawner (claude-code, codex,
	// gemini-cli). Returns nil for non-launchable agents.
	SpawnerFor func(agentName string) spawn.Spawner

	// LaunchFix delegates to agentlaunch.LaunchFixAgent in production.
	LaunchFix func(ctx context.Context, agentName string, prompt string) error

	// LoopRun, when non-nil, replaces RunInvestigateLoop.
	LoopRun func(ctx context.Context, in LoopInput, ldeps LoopDeps) (LoopResult, error)

	// PromptYN is the interactive y/N prompt used by the settings migration
	// and the HEAD-soft-warn. Nil means "use the real huh-backed prompt".
	PromptYN func(ctx context.Context, question string, def bool) (bool, error)

	// HeadHasInvestigateCheckpoint returns (true, info) when the
	// checkpoint at HEAD already has HasInvestigation set. Used to
	// soft-warn against running a redundant investigation. Nil means
	// "skip the check entirely".
	HeadHasInvestigateCheckpoint func(ctx context.Context) (bool, string)

	// InvestigateMultipicker overrides the spawn-time agent picker. Nil
	// means "use the real PickInvestigateAgents form".
	InvestigateMultipicker func(ctx context.Context, choices []AgentChoice, askPrompt bool) (PickedInvestigate, error)
}

type Files struct {
	// Findings is the absolute path to the findings document the agent
	// reads, edits, and adds evidence to.
	Findings string
	// State is the absolute path to the run's state.json file. The agent
	// records its stance there via the `pending_turn` field.
	State string
}

type FixDeps struct {
	// ManifestStore loads local manifests by run ID.
	ManifestStore *LocalManifestStore

	// FixAgent is the agent registry name to launch. When empty, RunFix
	// falls back to defaultFixAgent.
	FixAgent string

	// Launch runs the actual coding agent session. Production wires this
	// to agentlaunch.LaunchFixAgent.
	Launch func(ctx context.Context, agentName string, prompt string) error

	// ReadFile, when non-nil, replaces os.ReadFile.
	ReadFile func(name string) ([]byte, error)
}

type FixInput struct {
	// RunID resolves a specific run; empty means "pick the most recent".
	RunID string

	// Out is the user-facing stream for the launch banner.
	Out io.Writer

	// ErrOut is the user-facing stream for warnings (e.g. missing doc).
	ErrOut io.Writer
}

type IssueLinkResult struct {
	// SeedDoc is the rendered markdown body — ready to write to a
	// findings doc via Bootstrap.IssueLinkSeed.
	SeedDoc []byte
	// Topic is the human-readable topic. Prefers the issue/PR title; if
	// the title is empty, falls back to the URL.
	Topic string
}

type LocalManifest struct {
	// RunID is the 12-hex-char investigation run identifier.
	RunID string `json:"run_id"`

	// Topic is the human-readable subject of the investigation.
	Topic string `json:"topic"`

	// Slug is the filesystem-safe form of Topic, derived via SlugifyTopic.
	Slug string `json:"slug"`

	// StartingSHA is the git commit SHA that was HEAD when the
	// investigation started.
	StartingSHA string `json:"starting_sha"`

	// WorktreePath is the absolute path to the worktree the run executed
	// in. Empty when the run was not associated with a specific
	// worktree.
	WorktreePath string `json:"worktree_path,omitempty"`

	// FindingsDoc is the absolute path to the findings document the run
	// produced. Always absolute — callers (writeRunManifest in particular)
	// must resolve repo-relative paths before populating this field, since
	// `entire investigate show` / `fix` read it back via os.ReadFile and
	// do not perform their own resolution. The on-disk file is removed for
	// terminal outcomes (Quorum/Stalled) once FindingsContent has been
	// captured — the path remains here for resumable runs (Paused /
	// Cancelled) where the file still lives in the per-run directory.
	FindingsDoc string `json:"findings_doc,omitempty"`

	// FindingsContent embeds the final findings.md content as of run
	// end. Populated on terminal outcomes (Quorum/Stalled) so the
	// findings survive after the per-run directory is cleaned up. Empty
	// on Paused/Cancelled — those runs are resumable and the file lives
	// on disk in the per-run directory at FindingsDoc.
	FindingsContent string `json:"findings_content,omitempty"`

	// Agents is the ordered list of agent names that participated in
	// the run.
	Agents []string `json:"agents"`

	// Outcome is the terminal outcome of the run. One of: "quorum",
	// "stalled", "paused", "cancelled".
	Outcome string `json:"outcome"`

	// StancesByAgent records the LAST stance each agent expressed in
	// the run, keyed by agent name. Empty when the run terminated
	// without any stances being recorded.
	StancesByAgent map[string]string `json:"stances_by_agent,omitempty"`

	// StartedAt is when the run was initiated.
	StartedAt time.Time `json:"started_at"`

	// EndedAt is when the run terminated.
	EndedAt time.Time `json:"ended_at"`
}

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

type LoopDeps struct {
	// SpawnerFor maps an agent name → Spawner. Returns nil for an unknown
	// agent name, in which case the loop pauses with an error.
	SpawnerFor func(agentName string) spawn.Spawner

	// States persists/loads RunState across turns. In production this is
	// a *StateStore rooted at <git-common-dir>/entire-investigations.
	States *StateStore

	// Progress receives turn lifecycle events. Production wires either a
	// tuiProgressSink (TTY) or textProgressSink (non-TTY). nil is treated
	// as nullProgressSink (no-op).
	Progress ProgressSink

	// Now returns the current time. Defaults to time.Now if nil.
	Now func() time.Time
}

type LoopInput struct {
	RunID        string    // 12-hex
	Topic        string    // human-readable subject of the investigation
	Agents       []string  // ordered, length >= 1
	MaxTurns     int       // per-agent turn budget; 0 → defaultMaxTurns (2)
	Quorum       int       // approvals needed; 0 → len(Agents)
	AlwaysPrompt string    // optional, appended verbatim to every prompt
	FindingsDoc  string    // absolute path
	StartingSHA  string    // git HEAD when `entire investigate` was invoked
	Resume       *RunState // when non-nil, resume from this state
}

type LoopOutcome string

type LoopResult struct {
	Outcome LoopOutcome
	State   *RunState
	// Err holds the most recent per-turn spawn error, if any. Informational:
	// when Outcome is Quorum/Stalled it is typically nil. When Outcome is
	// Paused this surfaces the underlying agent failure.
	Err error
}

type PendingTurn struct {
	Stance string `json:"stance"`         // "approve" | "request-changes" | "reject"
	Note   string `json:"note,omitempty"` // short explanation; optional
}

type PickedInvestigate struct {
	Names  []string
	Prompt string
}

type ProgressSink interface {
	// TurnStarted is called immediately before the agent process starts for
	// the given turn. perAgentTurn is the 1-indexed count of turns this
	// agent has taken (this one included); maxPerAgent is the configured
	// per-agent budget.
	TurnStarted(agent string, turn, perAgentTurn, maxPerAgent int)

	// TurnFinished is called once after the agent process exits AND the
	// timeline doc has been parsed for the freshly-added turn block. stance
	// is one of "approve", "request-changes", "reject", "unknown". duration
	// is the wall-clock duration of the agent process. failed is true when
	// the turn was treated as a failure by the loop (spawn error, missing
	// heading, etc.); err is the underlying error or nil.
	TurnFinished(agent string, turn int, stance string, duration time.Duration, failed bool, err error, preview string)

	// RunFinished is called once when the loop terminates (any outcome).
	// The TUI uses this to flip rows to a terminal status and freeze the
	// dashboard; the text sink may print a final outcome line.
	RunFinished(outcome LoopOutcome)
}

type RunState struct {
	RunID           string       `json:"run_id"`
	Topic           string       `json:"topic"`
	Agents          []string     `json:"agents"`
	MaxTurns        int          `json:"max_turns"`
	Quorum          int          `json:"quorum"`
	CompletedRounds int          `json:"completed_rounds"`
	Turn            int          `json:"turn"`           // overall turn index across rounds
	NextAgentIdx    int          `json:"next_agent_idx"` // index into Agents for the NEXT turn
	Stances         []TurnStance `json:"stances,omitempty"`
	FindingsDoc     string       `json:"findings_doc"` // absolute path
	StartingSHA     string       `json:"starting_sha"`
	StartedAt       time.Time    `json:"started_at"`
	UpdatedAt       time.Time    `json:"updated_at"`

	// PendingTurn is the agent-writable section. After each agent turn the
	// agent sets this to its stance + a short note. The loop reads it
	// after the agent process exits, validates it, appends a TurnStance to
	// Stances[], clears PendingTurn, advances cursors, persists.
	PendingTurn *PendingTurn `json:"pending_turn,omitempty"`
}

type ShowDeps struct {
	ManifestStore *LocalManifestStore
}

type ShowInput struct {
	// RunID is the run id (or run-id prefix) to display. Empty means
	// "show the only manifest, or list options if more than one exists".
	RunID string
	// Out is the destination writer for the rendered summary + findings.
	Out io.Writer
	// ErrOut is the destination writer for user-facing error/help messages.
	ErrOut io.Writer
}

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

type TurnStance struct {
	Round       int    `json:"round"`
	Turn        int    `json:"turn"` // overall turn number
	Agent       string `json:"agent"`
	Stance      string `json:"stance"` // "approve" | "request-changes" | "reject" | "unknown"
	PlanChanged bool   `json:"plan_changed"`
	Note        string `json:"note,omitempty"`
}