watchd

type AsyncValidateResponse struct {
	TaskID string `json:"task_id"`
}

type CollectResponse struct {
	Tasks []TaskState `json:"tasks"`
}

type CommandReg struct {
	CommandID   string    `json:"command_id"`
	SidecarID   string    `json:"sidecar_id"`
	ProjectRoot string    `json:"project_root"`
	Op          string    `json:"op"`
	Name        string    `json:"name"`
	SubmittedAt time.Time `json:"submitted_at"`
}

type CommandState struct {
	CommandID   string     `json:"command_id"`
	SidecarID   string     `json:"sidecar_id"`
	Op          string     `json:"op"`
	Name        string     `json:"name"`
	SubmittedAt time.Time  `json:"submitted_at"`
	EndedAt     *time.Time `json:"ended_at,omitempty"`
	ExitCode    *int       `json:"exit_code,omitempty"`
	Running     bool       `json:"running"`
	Bytes       int64      `json:"bytes"`
	Truncated   bool       `json:"truncated"`
}

type ConflictReport struct {
	Root string `json:"root"`
	// Conflict is nil when the daemon has no answer for this root — either it
	// does not know the project, or no check has run yet.
	Conflict *ConflictState `json:"conflict,omitempty"`
	// Known reports whether the daemon is tracking the root at all. Without it
	// "unknown project" and "checked, nothing to report" are the same response.
	Known bool `json:"known"`
}

type ConflictState struct {
	// Branch is the branch that was compared, empty when there was none.
	Branch string `json:"branch,omitempty"`
	// Target is the merge target, qualified as the remote names it —
	// "origin/main".
	Target string `json:"target,omitempty"`
	// HeadSHA and TargetSHA are the two commits actually merged. They are what
	// makes a result reusable: neither side moving means the merge would
	// resolve identically.
	HeadSHA   string `json:"head_sha,omitempty"`
	TargetSHA string `json:"target_sha,omitempty"`
	// Conflicted reports that the merge does not resolve automatically. False
	// with an empty Unavailable is a real all-clear; false with Unavailable set
	// means no merge was attempted.
	Conflicted bool `json:"conflicted"`
	// Paths lists the conflicted paths, capped at MaxConflictPaths.
	Paths []string `json:"paths,omitempty"`
	// TotalPaths is how many paths conflicted in total, which exceeds len(Paths)
	// when the list was cut.
	TotalPaths int `json:"total_paths,omitempty"`
	// CheckedAt is when the answer was produced, TargetFetchedAt when the
	// target's remote-tracking ref was last refreshed. The second is the one
	// that decides how much the answer is worth.
	CheckedAt       time.Time `json:"checked_at"`
	TargetFetchedAt time.Time `json:"target_fetched_at"`
	// TargetStale reports that the last refresh of the target ref failed, so
	// the comparison ran against whatever was already on disk. The answer may
	// simply be out of date, which is worth saying rather than implying.
	TargetStale bool `json:"target_stale,omitempty"`
	// Unavailable explains why there is no answer, and is empty when there is
	// one. A detached HEAD, a repo with no recorded default branch, and a
	// branch that is itself the merge target all land here — none of them are
	// faults, and all of them would otherwise look like "no conflicts".
	Unavailable string `json:"unavailable,omitempty"`
}

type OutputChunk struct {
	// Data is raw command output, exactly as the remote command wrote it —
	// interleaved stdout and stderr, ANSI and carriage returns intact.
	Data []byte `json:"data"`
	// NextOffset is the offset to pass on the following read.
	NextOffset int64 `json:"next_offset"`
	Running    bool  `json:"running"`
	ExitCode   *int  `json:"exit_code,omitempty"`
	// Truncated reports that output before the returned data was evicted and is
	// gone. Saying so is the difference between showing a partial run and
	// showing a partial run that looks whole.
	Truncated bool `json:"truncated"`
	// Found is false when the daemon knows nothing about the command.
	Found bool `json:"found"`
	// Error explains why streaming stopped early, when it did. Without it a
	// failed stream is indistinguishable from a command that produced no output,
	// which sends the reader looking for a bug in their own command.
	Error string `json:"error,omitempty"`
}

type PRCheck struct {
	Name       string `json:"name"`
	Status     string `json:"status"`     // QUEUED, IN_PROGRESS, COMPLETED
	Conclusion string `json:"conclusion"` // SUCCESS, FAILURE, NEUTRAL, CANCELLED, etc.
}

type PRComment struct {
	Author    string    `json:"author"`
	Body      string    `json:"body"`
	CreatedAt time.Time `json:"created_at"`
	Resolved  bool      `json:"resolved,omitempty"`
}

type PRState struct {
	Number           int         `json:"number"`
	Title            string      `json:"title"`
	URL              string      `json:"url"`
	UpdatedAt        time.Time   `json:"updated_at,omitempty"`
	CheckState       string      `json:"check_state,omitempty"` // rollup: SUCCESS, FAILURE, PENDING, ERROR, EXPECTED
	Checks           []PRCheck   `json:"checks,omitempty"`
	Comments         []PRComment `json:"comments,omitempty"`
	ChangesRequested bool        `json:"changes_requested,omitempty"`
	FetchedAt        time.Time   `json:"fetched_at"`
}

type ProjectSnapshot struct {
	Root     string           `json:"root"`
	Branch   string           `json:"branch"`
	HeadRef  string           `json:"head_ref"`
	RepoName string           `json:"repo_name"`
	Sidecars []SidecarState   `json:"sidecars"`
	Events   []eventlog.Event `json:"events"`
	Commands []CommandState   `json:"commands,omitempty"`
	// Conflict is nil until the first conflict check for this project has run.
	// Nil is "not known yet", distinct from a ConflictState reporting no
	// conflict, and the two must not be collapsed by a reader.
	Conflict *ConflictState `json:"conflict,omitempty"`
	// PR is the advisory PR state for the current branch. Nil when no open PR
	// exists, or when GitHub credentials are not configured.
	PR *PRState `json:"pr,omitempty"`
}

type Resources struct {
	CPUPercent     float64   `json:"cpu_percent"`
	MemUsedBytes   int64     `json:"mem_used_bytes"`
	MemLimitBytes  int64     `json:"mem_limit_bytes"`
	DiskUsedBytes  int64     `json:"disk_used_bytes"`
	DiskTotalBytes int64     `json:"disk_total_bytes"`
	SampledAt      time.Time `json:"sampled_at"`
}

type RiskSummary struct {
	// Score is 0–100. Higher means more caution: bigger, broader, or already
	// failing. It does not decide anything on its own; see decideRisk.
	Score int `json:"score"`
	// Lines and Files are what was measured, kept apart from the score so a
	// caller can compare two changes without unpicking one.
	Lines int `json:"lines"`
	Files int `json:"files"`
	// Inert reports that every changed path was docs or text.
	Inert bool `json:"inert,omitempty"`
	// Band is Score bucketed into BandLow, BandMedium or BandHigh.
	Band string `json:"band"`
	// Parts are the facts behind the score, each with what it contributed.
	Parts []string `json:"parts,omitempty"`
	// Advice is what a developer or agent could do about it, or "" when there is
	// nothing useful to say.
	Advice string `json:"advice,omitempty"`
}

type SidecarState struct {
	ID   string `json:"id"`
	Name string `json:"name"`
	// SessionID is the agent session that owns this sidecar, empty for state
	// written outside a session or before sessions existed. Sidecars are
	// isolated per session, so two entries for one project and branch are two
	// sessions working in the same tree — this is what tells them apart.
	SessionID    string    `json:"session_id,omitempty"`
	ProjectName  string    `json:"project_name"`
	RepoName     string    `json:"repo_name"`
	SnapshotName string    `json:"snapshot_name"`
	FileMtime    time.Time `json:"file_mtime"`
	// Workspace is the sidecar-side repo path, used to sample disk usage where
	// the work actually happens rather than wherever a shell starts.
	Workspace    string      `json:"workspace,omitempty"`
	LastActivity time.Time   `json:"last_activity"`
	LastOp       eventlog.Op `json:"last_op"`
	LastLevel    string      `json:"last_level"`
	Running      bool        `json:"running"`
	// Resources is the most recent resource sample, or nil when none has
	// arrived — sampling only runs while a dashboard is attached.
	Resources *Resources `json:"resources,omitempty"`
}

type Snapshot struct {
	Projects []ProjectSnapshot `json:"projects"`
	// AuthError explains why output streaming is unavailable, when it is. An
	// empty logs pane with no explanation sends people hunting the wrong fault,
	// so the daemon reports this rather than silently serving nothing.
	AuthError string `json:"auth_error,omitempty"`
}

type TaskState struct {
	ID string `json:"id"`
	// ProjectRoot is the key the task is filed under — the root of the repo,
	// which may sit above the directory the run was actually asked for. See
	// taskStore.projectKey.
	ProjectRoot string    `json:"project_root"`
	StartedAt   time.Time `json:"started_at"`
	FinishedAt  time.Time `json:"finished_at,omitempty"`
	Running     bool      `json:"running"`
	// ExitCode is the validate run's exit status. Meaningful only once the task
	// has finished.
	ExitCode int `json:"exit_code"`
	// Output is what the run printed, held for whoever collects the result.
	// Capped at maxTaskOutput, keeping the tail.
	Output string `json:"output,omitempty"`
	// Stale reports that the working tree changed between the run starting and
	// its result being read, so the result describes code that is no longer on
	// disk. For a live-tree run ExitCode and Output are cleared when it is set: a
	// stale task is reported so that the discard is visible, and carrying the
	// verdict would invite it to be read as one. For a snapshot run they are
	// kept — see Snapshot, where the verdict outlives the tree moving.
	//
	// The tree most often moved because of the run itself — output written,
	// goldens regenerated, a lockfile touched. Reporting the discard is what
	// lets that be diagnosed instead of looking like no run happened.
	//
	// It is not a fix for the cause. A mid-run edit by the developer and a file
	// written by the run are the same event as far as a content digest is
	// concerned, so nothing here can tell them apart, and relaxing the
	// comparison to let artifacts through would let a real edit through with
	// them — trading a silence for a false pass, which is the one direction this
	// store must not fail in. Actually keeping the result means stopping the
	// tree from moving under the run, which is a matter of where the run
	// happens rather than how its result is judged.
	Stale bool `json:"stale"`
	// Snapshot reports that the run validated a checked-out copy of the tree
	// rather than the tree itself. Such a result is exact about the state it
	// ran against whatever happened afterwards, so it is reported even when
	// stale — qualified rather than thrown away.
	Snapshot bool `json:"snapshot,omitempty"`
	// DeliveredAt records when this result was handed to a caller. A stamped
	// task is never reported again; an unstamped one is still owed to somebody.
	//
	// It exists so that handing a result over and forgetting it are two steps
	// rather than one. See taskStore.collect.
	DeliveredAt time.Time `json:"delivered_at,omitempty"`
}

type ValidateRequest struct {
	// Args is os.Args[1:] from the caller, e.g. ["validate", "test", "--remote"].
	Args []string `json:"args"`
	// CircleCIToken is forwarded to the subprocess as CIRCLE_TOKEN.
	CircleCIToken string `json:"circleci_token,omitempty"`
	// Env is the caller's os.Environ(), forwarded verbatim to the subprocess so
	// session-identity variables (e.g. CLAUDE_CODE_SESSION_ID) reach it intact.
	Env []string `json:"env,omitempty"`
	// ProjectRoot is the repo the run applies to, already resolved by the client
	// (so it reflects the caller's --project, or its cwd). It decides what gets
	// validated, and it is also what a task is filed and fingerprinted under,
	// what a change is measured against, and what a verdict is remembered by —
	// so anything the daemon decides on a project's behalf needs it.
	//
	// It cannot be left to the daemon to infer. The daemon's own cwd is wherever
	// it was launched from, which is one arbitrary repo out of all the repos it
	// serves, so a run that resolved the project itself would validate that one
	// and report the answer under whichever project asked. Empty is accepted on
	// the synchronous path only, for a client too old to send it; such a run is
	// simply run, with nothing judged or recorded.
	ProjectRoot string `json:"project_root,omitempty"`
	// AllowAsync says the caller will accept being released before the answer
	// exists. It is an offer, not an instruction: the daemon weighs the change
	// and may hold the caller anyway.
	//
	// Only a caller that has somewhere to hear the answer later should set it.
	// A hook does — the next turn collects background results — while a developer
	// watching a terminal does not, and releasing them would leave the run's
	// output going nowhere they are looking.
	AllowAsync bool `json:"allow_async,omitempty"`
}

type ValidateResponse struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
	// TaskID is set when the daemon took the run into the background rather than
	// running it here. Nothing has run yet: ExitCode is zero because there is no
	// exit code, and the result is collected on a later turn.
	TaskID string `json:"task_id,omitempty"`
	// Risk is what the daemon made of the change: a score, the facts behind it,
	// and any advice. Nil when the caller never offered to be released, since
	// then no change was judged.
	Risk *RiskSummary `json:"risk,omitempty"`
	// Reason says why the run was released or held, in words a caller can print
	// as one line. Empty when the caller never offered to be released, since
	// then there was no decision to explain.
	Reason string `json:"reason,omitempty"`
}

type ValidateRunner func(ctx context.Context, projectRoot string, args []string, env []string, stdout, stderr io.Writer) int