watchd

type AsyncValidateResponse struct {
	TaskID string `json:"task_id"`
	// ClaimWarning is an advisory when another session is actively validating
	// overlapping paths. Empty in the common case (no overlap). Never a gate.
	ClaimWarning string `json:"claim_warning,omitempty"`
}

type ClaimState struct {
	SessionID   string `json:"session_id"`
	ProjectRoot string `json:"project_root"`
	// Paths are the repo-relative paths changed in this session's working tree,
	// captured at claim registration time. Nil means the change could not be
	// measured; treat as potentially overlapping anything in the project.
	Paths     []string  `json:"paths,omitempty"`
	ClaimedAt time.Time `json:"claimed_at"`
	ExpiresAt time.Time `json:"expires_at"`
}

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 Connection struct {
	// Remote is the TCP address of a remote daemon, empty for the local socket.
	Remote string
}

type EditedSinceError struct{ Paths []string }

type FileChange struct {
	Path       string `json:"path"`
	Insertions int    `json:"insertions"`
	Deletions  int    `json:"deletions"`
}

type FixState string

type Option func(*daemonOptions)

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"`
	// ActiveClaims lists validate claims from all sessions currently active for
	// this project. Nil when no sessions are validating.
	ActiveClaims []ClaimState `json:"active_claims,omitempty"`
	// Sessions lists this project's pre-PR sessions, newest first. State only:
	// the text of a review is fetched on demand through GET /session/{id}.
	Sessions []Session `json:"sessions,omitempty"`
}

type PromptRunState string

type ProvisionRequest struct {
	OrgID string `json:"org_id"`
	Name  string `json:"name"`
	Image string `json:"image,omitempty"`
}

type ProvisionResponse struct {
	SidecarID string `json:"sidecar_id"`
}

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 RestorePoint struct {
	// Ref is the git ref that holds the snapshot, so it survives garbage
	// collection and a daemon restart.
	Ref     string    `json:"ref"`
	HeadSHA string    `json:"head_sha"`
	SavedAt time.Time `json:"saved_at"`
	// Paths are the files the session's fixes changed: what a restore puts back.
	Paths    []string `json:"paths,omitempty"`
	Restored bool     `json:"restored,omitempty"`
}

type RestoreRequest struct {
	// Force restores even files that were edited after the session changed them,
	// discarding those edits.
	Force bool `json:"force,omitempty"`
}

type RestoreResult struct {
	Paths []string `json:"paths"`
}

type ReviewConfig struct {
	Credential review.Credential
	// BaseURL is forwarded to claude when it is not Anthropic's own.
	BaseURL string
	// AuthError explains a missing Credential, reported in the snapshot so an
	// absent capability is explained rather than silent.
	AuthError string

	// The fields below are test seams. Left nil, the daemon builds a real pool
	// from its CircleCI client and talks to the sandbox through it.
	NewPool func(ctx context.Context, spec ReviewPoolSpec) (*ReviewPool, error)
	Submit  SubmitFunc
	Stream  StreamFunc
}

type ReviewPool struct {
	Acquire   func(context.Context) (*sidecar.PoolEntry, error)
	Release   func(*sidecar.PoolEntry)
	WaitReady func(context.Context) error
	Close     func(context.Context)
}

type ReviewPoolSpec struct {
	// Root is the tracked project; its config decides org and image.
	Root string
	// WorkDir is the tree synced to the sandboxes: the user's project itself.
	WorkDir string
	Size    int
}

type ReviewPrompt struct {
	Name      string         `json:"name"`
	State     PromptRunState `json:"state"`
	SidecarID string         `json:"sidecar_id,omitempty"`
	// CommandID names the buffered output of this review's Claude run, readable
	// through /output while it runs and after.
	CommandID  string `json:"command_id,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`
	Error      string `json:"error,omitempty"`
	// Findings counts the structured findings parsed from this review's output.
	Findings int `json:"findings,omitempty"`
}

type ReviewResult struct {
	Prompt    string `json:"prompt"`
	SidecarID string `json:"sidecar_id,omitempty"`
	// Output is Claude's prose, capped at maxReviewOutput.
	Output     string `json:"output,omitempty"`
	Error      string `json:"error,omitempty"`
	DurationMS int64  `json:"duration_ms,omitempty"`
	// Findings are the structured findings the review gave, each with an ID
	// unique within the round. Empty when it gave none or failed; Error tells
	// the two apart.
	Findings []review.Finding `json:"findings,omitempty"`
	// FindingsDropped counts findings that were unusable or over the cap.
	FindingsDropped int `json:"findings_dropped,omitempty"`
}

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 Round struct {
	Number  int            `json:"number"`
	State   RoundState     `json:"state"`
	Reviews []ReviewPrompt `json:"reviews"`
	// Findings counts every finding the round's reviews reported; Worth counts
	// the ones worth changing (severity high or medium).
	Findings int       `json:"findings"`
	Worth    int       `json:"worth"`
	Fix      *RoundFix `json:"fix,omitempty"`
	// Note says why the round ended the way it did, such as why the loop stopped.
	Note      string     `json:"note,omitempty"`
	StartedAt time.Time  `json:"started_at"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
}

type RoundDetail struct {
	Number  int            `json:"number"`
	Results []ReviewResult `json:"results,omitempty"`
}

type RoundFix struct {
	State      FixState     `json:"state"`
	Files      []FileChange `json:"files,omitempty"`
	Insertions int          `json:"insertions,omitempty"`
	Deletions  int          `json:"deletions,omitempty"`
	// FindingIDs are the findings the agent was asked to fix.
	FindingIDs []string `json:"finding_ids,omitempty"`
	Error      string   `json:"error,omitempty"`
}

type RoundState string

type Session struct {
	ID          string `json:"id"`
	ProjectRoot string `json:"project_root"`
	Branch      string `json:"branch,omitempty"`
	HeadSHA     string `json:"head_sha,omitempty"`

	State SessionState `json:"state"`
	// PauseReason says why a paused session is waiting, and PausedPaths which
	// files changed underneath it.
	PauseReason string   `json:"pause_reason,omitempty"`
	PausedPaths []string `json:"paused_paths,omitempty"`
	Error       string   `json:"error,omitempty"`

	// Stages is always the full flow, in order.
	Stages []Stage `json:"stages"`
	Rounds []Round `json:"rounds"`
	// Restore is nil until the first fix is about to change the user's files.
	Restore *RestorePoint `json:"restore,omitempty"`

	StartedAt time.Time  `json:"started_at"`
	EndedAt   *time.Time `json:"ended_at,omitempty"`
}

type SessionDetail struct {
	Session
	Details []RoundDetail `json:"details,omitempty"`
}

type SessionList struct {
	Sessions []Session `json:"sessions"`
}

type SessionRefused struct {
	Status  int
	Message string
}

type SessionRequest struct {
	// ProjectRoot is a project the daemon tracks. Required.
	ProjectRoot string `json:"project_root"`
	// PromptsDir is a directory of review prompts relative to the project root;
	// empty means .chunk/reviews. Absolute paths and paths that leave the
	// project are refused.
	PromptsDir  string `json:"prompts_dir,omitempty"`
	Parallelism int    `json:"parallelism,omitempty"`
	Model       string `json:"model,omitempty"`
	// TimeoutSeconds bounds each review; zero means review.DefaultTimeout.
	TimeoutSeconds int `json:"timeout_seconds,omitempty"`
	// MaxRounds lowers the number of rounds; zero or more than MaxRounds means
	// MaxRounds.
	MaxRounds int `json:"max_rounds,omitempty"`
}

type SessionStartResponse struct {
	ID string `json:"id"`
}

type SessionState string

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"`
	// OrgID is the org the sidecar lives in: the one its state file records, or
	// the project's org for state written before that was recorded.
	OrgID string `json:"org_id,omitempty"`

	// Verified reports that the API's sidecar list confirmed this sidecar
	// exists. Sidecars the list has confirmed gone never reach a snapshot, so
	// false means only that nothing has confirmed it yet.
	Verified     bool        `json:"verified,omitempty"`
	LastActivity time.Time   `json:"last_activity"`
	LastOp       eventlog.Op `json:"last_op"`
	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"`
	// contains filtered or unexported fields
}

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"`
	// ReviewAuthError explains why the daemon cannot run sessions (no Claude
	// credential, or no CircleCI login), empty when it can. It never contains
	// the credential itself.
	ReviewAuthError string `json:"review_auth_error,omitempty"`
}

type Stage struct {
	ID    StageID    `json:"id"`
	State StageState `json:"state"`
	// Note says more about the state: why a loop ended, what failed.
	Note string `json:"note,omitempty"`
}

type StageID string

type StageState string

type StreamFunc func(ctx context.Context, entry *sidecar.PoolEntry, commandID string, onOutput circleci.OutputFn) (int, error)

type SubmitFunc func(ctx context.Context, entry *sidecar.PoolEntry, script string, env map[string]string) (string, error)

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"`
	// OrgID is the CircleCI org UUID for this project. When set and the daemon
	// has credentials, the daemon provisions a fresh sidecar for the run rather
	// than expecting one to already be registered on its filesystem.
	OrgID string `json:"org_id,omitempty"`
	// HookCodex says the run is a hook invocation from Codex, and the daemon
	// passes it on to the run as --hook-codex.
	//
	// It travels as a field rather than in Args because a remote daemon's build
	// cannot be checked, and one that predates the flag would reject the whole
	// run with a non-blocking exit — a commit gate would pass having checked
	// nothing. A daemon that predates this field ignores it instead, and the run
	// goes ahead, just without Codex's quieter output.
	HookCodex bool `json:"hook_codex,omitempty"`
	// WorkDir is the caller's working directory, which the daemon passes to the
	// subprocess as --project so it can load .chunk/config.json from the right
	// location. It equals ProjectRoot for callers whose working directory is the
	// git top-level; it differs when the .chunk directory sits below the git root.
	//
	// A daemon that predates this field ignores it and falls back to ProjectRoot,
	// which is the caller's cwd and therefore also correct in the common case.
	WorkDir string `json:"work_dir,omitempty"`
	// SidecarImage is the image the caller resolved for this run from its own
	// config, per-command override included. The daemon boots the sidecar it
	// provisions from it, since the subprocess is handed that sidecar by ID and
	// never picks an image itself. A remote daemon may not have the checkout to
	// read the config from, so the client resolving it is what makes the image
	// right there.
	//
	// Empty means the caller configured none, or predates this field; the daemon
	// then reads validation.sidecarImage from the project's config itself.
	SidecarImage string `json:"sidecar_image,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"`
	// ClaimWarning is an advisory when another session is actively validating
	// overlapping paths. Empty in the common case (no overlap). Never a gate.
	ClaimWarning string `json:"claim_warning,omitempty"`
}

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