engine

type AgentsAllowOptions struct {
	For          string // 1h, 6h (default), 1d, 7d, 15d, 30d or 90d
	UntilRevoked bool
}

type AgentsAllowResult struct {
	Grant    grant.Grant      `json:"grant"`
	Replaced *grant.Grant     `json:"replaced"`
	Preview  *preview.Preview `json:"preview"`
}

type AgentsRevokeResult struct {
	Revoked []grant.Grant    `json:"revoked"`
	Preview *preview.Preview `json:"preview"`
}

type AgentsStatusResult struct {
	Pair            string        `json:"pair"`
	Grants          []GrantStatus `json:"grants"`
	TokenCanPublish string        `json:"token_can_publish"`
	TokenKind       string        `json:"token_kind"`
	Token           TokenCheck    `json:"token"`
}

type ApplyOptions struct {
	Plan string // plan ID or path to a plan .json
	Yes  bool
	// Archive hands the published features off after the publish (6.5):
	// the person picks Archive or Keep at the console, or, without one,
	// Archive applies. false keeps them without asking (R3).
	Archive bool
	// Lookup is the pair to look in when the plan file isn't on this
	// machine (--repo or the checkout's; nil when none resolves). A plan
	// that is here names its own pair.
	Lookup *workspace.Pair
	// LookupErr is why a --repo that was passed named no pair here. A plan
	// this machine lacks then fails with it (PAIR_NOT_FOUND, say), so the
	// ledger and the caller see the same code (re-review N4).
	LookupErr error
}

type ApplyResult struct {
	PlanID       string           `json:"plan_id"`
	PublicBranch string           `json:"public_branch"`
	PublicPR     int              `json:"public_pr"`
	PRURL        string           `json:"pr_url"`
	Resumed      bool             `json:"resumed"`
	Approval     *ledger.Approval `json:"approval"`
	Waived       []WaivedFinding  `json:"waived"`
	Preview      *preview.Preview `json:"preview"`
	// PRs is every PR the plan opened, bottom first (one for a plan of one
	// feature); StackNumber is the native GitHub stack, null when none.
	// PublicBranch, PublicPR and PRURL are the top PR's.
	PRs         []plan.StackPR `json:"prs"`
	StackNumber *int           `json:"stack_number"`
	// KeepsHistory: some PR publishes more than one commit in preserve or
	// curated mode, which "Squash and merge" would flatten (F-31).
	// PublicRepo is the plan's public repo. Both are for next.
	KeepsHistory bool   `json:"-"`
	PublicRepo   string `json:"-"`
	// AfterPublish is what happened to each published feature's shadow
	// branch: archived, kept, or incomplete (ARCHIVE_INCOMPLETE). Never
	// null. Archived lists the features archived, bottom first.
	AfterPublish map[string]string `json:"after_publish"`
	Archived     []string          `json:"-"`
	// Landed: the plan's updates had already landed, so this run only
	// recorded them and archived nothing (finishLanded, R14), though the
	// run that died may have been asked to. For next.
	Landed bool `json:"-"`
	// contains filtered or unexported fields
}

type AuditMinutes struct {
	Billed        bool    `json:"billed"`
	ScheduledSync *string `json:"scheduled_sync"`
}

type AuditResult struct {
	Public       string           `json:"public"`
	Shadow       string           `json:"shadow"`
	Guards       []workflow.Guard `json:"guards"`
	GuardMode    string           `json:"guard_mode"` // ci.rewrite_repo_guards
	Secrets      AuditSecrets     `json:"secrets"`
	PushTriggers []string         `json:"push_triggers"`
	Minutes      AuditMinutes     `json:"minutes"`
	Overlay      []ManagedFile    `json:"overlay"`
}

type AuditSecrets struct {
	Referenced   []SecretRef `json:"referenced"`
	Listed       bool        `json:"listed"`
	Missing      []string    `json:"missing"`
	Inherit      []string    `json:"inherit"`      // "<path>:<job>"
	Environments []string    `json:"environments"` // "<path>:<job>"
}

type CancelledRun struct {
	ID       int64  `json:"id"`
	Workflow string `json:"workflow"`
	URL      string `json:"url"`
}

type ClosedFeature struct {
	Name     string            `json:"name"`
	PublicPR int               `json:"public_pr"`
	Deleted  map[string]string `json:"deleted"`
	// Reparented are the children moved onto main in the push that closed
	// it; never null.
	Reparented []string `json:"reparented"`
	// GatePRLeftOpen is the gate PR the close couldn't close, 0 when none;
	// for human output only.
	GatePRLeftOpen int `json:"-"`
}

type CommitInfo struct {
	Source  string   `json:"source"`
	Subject string   `json:"subject"`
	Author  string   `json:"author"` // "Name <email>" as committed
	Files   []string `json:"files"`  // paths it changes, overlay paths left out
}

type DoctorCheck struct {
	ID      string         `json:"id"`
	Status  string         `json:"status"`
	Message string         `json:"message"`
	Fix     string         `json:"fix"`
	FixArgv []string       `json:"-"`
	Details map[string]any `json:"details"`
	// Unregistered is the public repo a failing pair check is about when
	// it isn't set up here: next offers both init forms (F-27).
	Unregistered string `json:"-"`
	// PersonMessage and PersonFixArgv replace Message and the fix in the
	// output for people, when set: a person runs plain init where an agent
	// gets the --plan forms. The JSON keeps Message and Fix as they are.
	PersonMessage string   `json:"-"`
	PersonFixArgv []string `json:"-"`
}

type DoctorOptions struct {
	// Repo is --repo. Empty means the current checkout's pair; never the
	// workspace's only pair, so outside a checkout the pair checks skip.
	Repo    string
	Remotes []workspace.Remote // the current checkout's remotes
	Dir     string             // the current directory; "" when unknown
	// GitVersion is `git version`'s output, or GitErr why it didn't run.
	GitVersion string
	GitErr     error
	// Version and Commit are this binary's build.
	Version, Commit string
	// TokenErr is why no token resolved; the stored login is never
	// refreshed for doctor, since it writes nothing.
	TokenErr error
	// Login is the stored login when the token came from it, else nil.
	Login *auth.Login
	// WorkspaceErr is why the workspace couldn't be opened.
	WorkspaceErr error
	Getenv       func(string) string
	// ForPerson is a run whose output a person reads (not --json): only
	// then does doctor work out the plain init line for a repo that isn't
	// set up here (PersonMessage).
	ForPerson bool
}

type DoctorResult struct {
	Checks []DoctorCheck `json:"checks"`
	// UpdateCheck is the update checker's state from a fresh look (6.4a).
	// The CLI sets it; the engine never looks.
	UpdateCheck *updatecheck.Status `json:"update_check,omitempty"`
}

type DoctorSummary struct {
	OK      int      `json:"ok"`
	Warn    int      `json:"warn"`
	Fail    int      `json:"fail"`
	Skipped int      `json:"skipped"`
	Failed  []string `json:"failed"`
}

type Drift struct {
	Status string   `json:"status"` // clean | conflicts | unknown | n/a (branch gone)
	Files  []string `json:"files"`
}

type Engine struct {
	Forge forge.Forge
	WS    *workspace.Workspace
	Actor string
	Token string
	// TokenSource names where Token came from, for error messages.
	TokenSource string
	// LooksLikeAgent is auth.LooksLikeAgent for this run: it is likely an
	// agent or a script, not a person at a terminal. Doctor and agents
	// status read it to spot an agent on a person's stored login.
	LooksLikeAgent bool
	Now            func() time.Time
	// Sleep waits d, or returns ctx.Err() as soon as ctx is done.
	Sleep func(context.Context, time.Duration) error
	Rand  io.Reader
	// Progress receives the steps and notes of slow work; nil prints nothing.
	Progress     progress.Progress
	Approver     approval.Approver
	Grants       *grant.Store
	Waivers      *waiver.Store
	Editor       func(initial string) (string, error)
	NewScanner   func(leak.Rules) (leak.Scanner, error)
	PollInterval time.Duration
	SettleWindow time.Duration
	// CIAppearWindow is how long sync looks for the workflow runs its
	// pushes start; zero looks once. CIAppearPoll is how often it looks
	// (zero means DefaultCIAppearPoll).
	CIAppearWindow time.Duration
	CIAppearPoll   time.Duration
	DryRun         bool
	// OnPush observes every push before it happens (tests).
	OnPush func(op, remote string, refspecs []string)
	// contains filtered or unexported fields
}

type FeatureAbandonResult struct {
	Feature   string           `json:"feature"`
	Abandoned bool             `json:"abandoned"` // the new value
	Changed   bool             `json:"changed"`   // false when it already had that value
	Preview   *preview.Preview `json:"preview"`
}

type FeatureArchiveResult struct {
	Feature string `json:"feature"`
	// Changed is false when the feature was already archived.
	Changed bool `json:"changed"`
	// Archived is the record's archive; null under --plan before it exists.
	Archived *feature.Archived `json:"archived"`
	// Moved is every shadow ref the archive created or deleted, with its
	// SHA; never null.
	Moved  map[string]string `json:"moved"`
	GatePR *int              `json:"gate_pr"` // the gate draft PR closed; null when none was open
	// PublicPR and Branch are the PR and its public branch: push fixes there.
	PublicPR int              `json:"public_pr"`
	Branch   string           `json:"branch"`
	Preview  *preview.Preview `json:"preview"`
	// PRState is the public PR's state when the feature was already
	// archived (open, merged, closed or unknown), for next: a merged or
	// closed PR takes no more pushes. "" otherwise.
	PRState string `json:"-"`
}

type FeatureCloseResult struct {
	Feature      string            `json:"feature"`
	State        feature.State     `json:"state"`         // the state it was closed from
	Deleted      map[string]string `json:"deleted"`       // shadow ref -> SHA it pointed at; never null
	GatePR       *int              `json:"gate_pr"`       // the draft PR closed (by us, or by GitHub as its branch went), nil when none was open
	NeedsConsole bool              `json:"needs_console"` // closing takes a person at a console (not ClosableWithoutConsole); set under --plan too
	Approval     *ledger.Approval  `json:"approval"`      // console; nil under --plan, and when none was needed
	// Reparented are the children moved onto main in the push that closed
	// this feature; never null.
	Reparented []string         `json:"reparented"`
	Preview    *preview.Preview `json:"preview"`
	// GatePRLeftOpen is the gate PR the close couldn't close, 0 when none;
	// for human output only.
	GatePRLeftOpen int `json:"-"`
}

type FeatureListResult struct {
	Features []FeatureReport `json:"features"` // never null; abandoned only with all
}

type FeatureReport struct {
	Name   string        `json:"name"`
	State  feature.State `json:"state"`
	Branch string        `json:"branch"`
	Head   string        `json:"head"` // "" when the branch is gone
	Base   string        `json:"base"`
	// Parent is the feature it is stacked on, or "main"; "" when the record
	// couldn't be read. Children are the live features stacked directly on
	// it, by name, never null. Stack is the native GitHub stack its PR is in.
	Parent    string       `json:"parent"`
	Children  []string     `json:"children"`
	Stack     *int         `json:"stack"`
	Drift     Drift        `json:"drift"`
	Gate      *GateSummary `json:"gate"`      // nil when never gated
	PublicPR  *int         `json:"public_pr"` // nil when never published
	PRState   string       `json:"pr_state"`  // "", open, merged, closed, unknown
	PlanID    string       `json:"plan_id"`
	Moved     bool         `json:"moved"` // since publish; false when unpublished; for an archived feature, its archive head (and any archive ref) against the published head; otherwise meaningless when the branch is gone (branch_gone reads only PRState)
	Abandoned bool         `json:"abandoned"`
	// PR is how its open public PR compares with the feature; nil unless
	// it is published, the PR is open and the feature's branch exists.
	PR *PRSync `json:"pr,omitempty"`
	// Archived is set once the feature was handed off (6.5): its archive
	// ref and head.
	Archived *feature.Archived `json:"archived,omitempty"`
	// PublicBranch is the public branch it was published to, for next;
	// "" when unpublished.
	PublicBranch string `json:"-"`
	// PartlyArchived, for next: an archive ref exists but the record
	// isn't marked, so an archive stopped partway (feature archive
	// finishes it).
	PartlyArchived bool `json:"-"`
	// Error is why the feature couldn't be surveyed; set only with state
	// unreadable. feature show returns it as its error.
	Error string `json:"error,omitempty"`
	// contains filtered or unexported fields
}

type FeatureShowResult struct {
	Feature FeatureReport  `json:"feature"`
	Commits []CommitInfo   `json:"commits"` // the feature's own commits (since its fork point, else since public main), oldest first; [] when the branch is gone
	Ledger  []ledger.Entry `json:"ledger"`  // this pair's entries for this feature, oldest first
}

type FeatureStartOptions struct {
	// From is the feature to stack the new one on: it starts at that
	// feature's tip in the shadow repo and records it as its parent, with
	// the tip as forked_at. "" or "main" starts from shadow main.
	From string
}

type FeatureStartResult struct {
	Name   string `json:"name"`
	Branch string `json:"branch"`
	Base   string `json:"base"`
	// Parent is the feature this one is stacked on, or "main".
	Parent       string           `json:"parent"`
	Checkout     [][]string       `json:"checkout"`      // argvs that get the branch into a checkout, in order
	CheckoutHint string           `json:"checkout_hint"` // Checkout as one shell line
	Preview      *preview.Preview `json:"preview"`
	// contains filtered or unexported fields
}

type FoldOptions struct {
	Feature string // the stacked feature to fold into its parent
}

type FoldResult struct {
	Feature    string            `json:"feature"`    // the folded feature, now closed
	Parent     string            `json:"parent"`     // the feature it was folded into
	From       string            `json:"from"`       // the parent's head before
	To         string            `json:"to"`         // the parent's head now: the folded feature's head
	Reparented []string          `json:"reparented"` // the folded feature's children, now stacked on Parent; never null
	Deleted    map[string]string `json:"deleted"`    // the folded feature's refs deleted, with their SHAs; never null
	GatePR     *int              `json:"gate_pr"`    // its gate draft PR, closed; nil when none was open
	Preview    *preview.Preview  `json:"preview"`
}

type ForeignCommit struct{ SHA, Author, Subject string }

type GateResult struct {
	Feature     string `json:"feature"`
	FeatureHead string `json:"feature_head"`
	PublicMain  string `json:"public_main"`
	// Parent is the feature the gate stacked on; "" when it built on
	// public main.
	Parent string `json:"parent"`
	// Base is the commit the feature's own commits were replayed onto:
	// public main, R, the rebased tip of the features below it, or, for an
	// append to the feature's open PR, that PR's head H; "" when a stacked
	// gate stopped before the features below it were built.
	Base          string          `json:"base"`
	Overlay       string          `json:"overlay"`
	Candidate     string          `json:"candidate"`
	PublishedTree string          `json:"published_tree"`
	ScannedAs     string          `json:"scanned_as"` // the mode the leak scan covered: preserve scans every commit, squash and curated the final tree
	Commits       []CommitInfo    `json:"commits"`    // the replayed commits, oldest first; empty when the replay didn't finish
	Checks        string          `json:"checks"`
	FailedChecks  []string        `json:"failed_checks"`
	Leak          string          `json:"leak"`
	Findings      []leak.Finding  `json:"findings"`
	Waived        []WaivedFinding `json:"waived"`
	// RepoGuards is what the gate did with the public workflows' repo
	// guards in C; nil when no candidate was built.
	RepoGuards *workflow.GuardReport `json:"repo_guards"`
	// ShadowPR is the gate PR in the shadow repo; nil when none was opened
	// (the gate failed before CI, a dry run, or a reused gate this promote
	// didn't wait on).
	ShadowPR *int `json:"shadow_pr"`
	// Job names the gate's CI wait, for wait; nil when no candidate was
	// pushed (a leak, a conflict, a dry run, or a reused gate this promote
	// didn't wait on).
	Job *string `json:"job"`
	// Reused is set by promote when it reuses a fresh green gate instead of re-running it.
	Reused bool `json:"reused"`
	// Children and Chain place a stacked feature, with Parent: the features
	// stacked directly on it, and the unpublished stack from its bottom up
	// to it, which a promote of the stack lists. Both are empty, and Parent
	// is "", for a feature with neither a parent nor children; a bottom
	// feature with children has Parent "main" (stackView).
	Children []string `json:"children,omitempty"`
	Chain    []string `json:"chain,omitempty"`
	// Ready is the stack's readiness after a passing gate (F-12), for next;
	// empty for a feature on its own and for any other result.
	Ready   StackReadiness   `json:"-"`
	Preview *preview.Preview `json:"preview"`
	// Update is how the gate built the update of the feature's open PR
	// (append onto its head, or replace); absent for a first publish.
	Update *feature.GateUpdate `json:"update,omitempty"`
	// contains filtered or unexported fields
}

type GateSummary struct {
	Checks    string    `json:"checks"`
	Leak      string    `json:"leak"`
	ScannedAs string    `json:"scanned_as"`
	Fresh     bool      `json:"fresh"`
	At        time.Time `json:"at"`
	Job       *string   `json:"job"` // non-nil exactly when the gate is pending: what wait takes
}

type GrantStatus struct {
	grant.Grant
	Expired          bool   `json:"expired"`
	RemainingSeconds *int64 `json:"remaining_seconds"`
}

type GroupAccess struct {
	Missing  []string `json:"missing"`
	Unknown  []string `json:"unknown"`
	Optional []string `json:"optional_missing"`
}

type InitOptions struct {
	Public string
	Shadow string // default: <public>-shadow
	Adopt  bool
	// Schedule is sync.schedule for a new overlay: "" or config.ScheduleOff
	// leaves scheduled sync off, DefaultSyncSchedule turns it on. An
	// overlay that already exists keeps its config: init refuses with
	// BAD_FLAG, before pushing anything, if its schedule differs.
	Schedule string
}

type InitResult struct {
	Public           string           `json:"public"`
	Shadow           string           `json:"shadow"`
	CreatedShadow    bool             `json:"created_shadow"`
	Adopted          bool             `json:"adopted"`
	Resumed          bool             `json:"resumed"`
	MirroredBranches []string         `json:"mirrored_branches"`
	MirroredTags     []string         `json:"mirrored_tags"`
	OverlayCreated   bool             `json:"overlay_created"`
	DefaultBranchSet bool             `json:"default_branch_set"`
	Audit            *AuditResult     `json:"audit"`
	Preview          *preview.Preview `json:"preview"`
	// GuardInstalled: the push guard is installed in this checkout when
	// init finishes (installed by this run, or before it).
	GuardInstalled bool `json:"guard_installed"`
	// Doctor is doctor's summary after a guided init; nil otherwise.
	Doctor *DoctorSummary `json:"doctor"`
	// Guided and DoctorChecks are for human output only.
	Guided       bool          `json:"-"`
	DoctorChecks []DoctorCheck `json:"-"`
	// Ready is true once Init returned without an error; human output says
	// "ready" only then. It is not part of the JSON result.
	Ready bool `json:"-"`
}

type JobEvent struct {
	SchemaVersion string    `json:"schema_version"`
	Type          string    `json:"type"`
	Job           string    `json:"job"`
	At            time.Time `json:"at"`
	// waiting
	Candidate   string `json:"candidate,omitempty"`
	ShadowPR    int    `json:"shadow_pr,omitempty"`
	ShadowPRURL string `json:"shadow_pr_url,omitempty"`
	CITimeout   string `json:"ci_timeout,omitempty"`
	// check
	Name       string `json:"name,omitempty"`
	Status     string `json:"status,omitempty"`
	Conclusion string `json:"conclusion,omitempty"`
	// settled
	Outcome      string   `json:"outcome,omitempty"`
	FailedChecks []string `json:"failed_checks,omitempty"`
}

type JobRef struct{ Feature, Candidate string }

type LogOptions struct {
	Feature, Op, ActorPrefix, Pair string
	Since                          time.Time
	Limit                          int
}

type LogResult struct {
	Entries []ledger.Entry `json:"entries"` // newest first, never null
}

type ManagedFile struct {
	Path   string         `json:"path"`
	Status managed.Status `json:"status"`
}

type PRSync struct {
	Behind  int `json:"behind"`
	Foreign int `json:"foreign"`
}

type PromoteOptions struct {
	Feature string
	// Features is a stack, bottom first: promote a b c. One feature is the
	// same as Feature. Feature is always Features[0] once validated.
	Features []string
	// Modes and Titles set one branch's history mode and PR title in a
	// stack promote (--mode-for, --title-for), keyed by feature.
	Modes    map[string]string
	Titles   map[string]string
	Mode     string // squash, preserve or curated; "" means promote.default_mode
	Message  string
	Title    string
	Body     string
	Branch   string       // public branch name; defaults to the feature name
	Curate   string       // path to the --curate file (curated mode)
	Groups   []plan.Group // the --curate file's groups, as read (ValidatePromoteOptions loads them)
	PlanOnly bool
	Yes      bool
	Archive  bool // as ApplyOptions.Archive
	Detach   bool // gate and return the pending job without waiting on CI
}

type PromoteResult struct {
	Gate     *GateResult      `json:"gate"`
	Plan     *plan.Plan       `json:"plan"`
	PlanPath string           `json:"plan_path"`
	Findings []leak.Finding   `json:"findings"`
	Waived   []WaivedFinding  `json:"waived"`
	Applied  *ApplyResult     `json:"applied"`
	Preview  *preview.Preview `json:"preview"`
	// PRs is every PR the plan opens, bottom first, with numbers once
	// applied; StackNumber is the native GitHub stack, null when none.
	PRs         []plan.StackPR `json:"prs"`
	StackNumber *int           `json:"stack_number"`
}

type PullOptions struct {
	Feature string
}

type PullResult struct {
	Feature string `json:"feature"`
	From    string `json:"from"` // the feature branch's head before
	To      string `json:"to"`   // its head now; From when it didn't move
	// Adopted are the PR's commits Ghostbranch didn't publish, now in the
	// feature, oldest first; never null.
	Adopted []feature.AdoptedCommit `json:"adopted"`
	// Children are the live features stacked directly on it, when it moved
	// (To != From): they sit on its old commits until feature restack
	// moves them; never null.
	Children []string         `json:"children"`
	Preview  *preview.Preview `json:"preview"`
}

type RemoveResult struct {
	Public  string           `json:"public"`
	Shadow  string           `json:"shadow"`
	Grants  int              `json:"grants"`
	Waivers int              `json:"waivers"`
	Plans   []string         `json:"plans"`
	Dir     string           `json:"dir"`
	Preview *preview.Preview `json:"preview"`
}

type RestackOptions struct {
	Feature string
	// Onto re-parents Feature: "main", or the feature to stack it on. Empty
	// restacks the features above Feature onto their parents' tips.
	Onto string
}

type RestackResult struct {
	Feature   string            `json:"feature"`
	Onto      string            `json:"onto"`      // "" when it restacked the features above Feature
	Restacked []RestackedBranch `json:"restacked"` // never null
	Pending   []string          `json:"pending"`   // not reached because it stopped, the one it stopped at first; never null
	Preview   *preview.Preview  `json:"preview"`
	// StoppedOnConflict is true when the restack stopped at Pending[0] on a
	// conflict (REBASE_CONFLICT), not on Ctrl-C or a git failure.
	StoppedOnConflict bool `json:"-"`
	// contains filtered or unexported fields
}

type RestackedBranch struct {
	Feature  string `json:"feature"`
	Parent   string `json:"parent"`    // "main", or the feature it is stacked on now
	From     string `json:"from"`      // its head before
	To       string `json:"to"`        // its head now; From when only its record moved
	ForkedAt string `json:"forked_at"` // its fork point now; "" on main
}

type SecretRef struct {
	Name  string   `json:"name"`
	Files []string `json:"files"`
}

type StackReadiness struct {
	// GateFirst is the lowest feature below this one whose gate isn't
	// fresh, or doesn't link to the level below it: gate it first. "" when
	// every one below is ready.
	GateFirst string
	// StaleAbove are the features stacked directly on this one whose gates
	// aren't fresh on this gate.
	StaleAbove []string
	// Levels is the longest stack from the bottom, up through this feature
	// and on through its only fresh child at each step, every level fresh
	// and linked by tree to the one below (trap 51). nil with GateFirst.
	Levels []string
	// TitleFor are the levels with more than one gate commit: their PRs
	// need --title-for.
	TitleFor []string
	// Live are the features stacked directly on this one that aren't
	// archived: a handed-off child's PR is the person's (R12).
	Live []string
}

type StatusResult struct {
	Public        string          `json:"public"`
	Shadow        string          `json:"shadow"`
	PublicMain    string          `json:"public_main"`
	ShadowMain    string          `json:"shadow_main"` // "" when shadow main is missing
	ShadowBehind  bool            `json:"shadow_behind"`
	Overlay       string          `json:"overlay"`        // overlay commit
	OverlayStatus string          `json:"overlay_status"` // current | outdated (a managed file needs upgrade)
	ScheduledSync bool            `json:"scheduled_sync"`
	Features      []FeatureReport `json:"features"` // never null; abandoned included
}

type SyncBranch struct {
	Name   string `json:"name"`
	From   string `json:"from"`
	To     string `json:"to"`
	Status string `json:"status"` // up_to_date | created | fast_forwarded | diverged | push_failed
}

type SyncOptions struct {
	NoCancel bool
	NoClose  bool
}

type SyncResult struct {
	Public           string           `json:"public"`
	Shadow           string           `json:"shadow"`
	Action           string           `json:"action"`
	PublicMain       string           `json:"public_main"`
	ShadowMainBefore string           `json:"shadow_main_before"`
	ShadowMainAfter  string           `json:"shadow_main_after"` // where sync left shadow main; when its push failed, the SHA sync read
	Branches         []SyncBranch     `json:"branches"`
	CancelledRuns    []CancelledRun   `json:"cancelled_runs"`
	Closed           []ClosedFeature  `json:"closed"`          // merged features sync closed; never null
	Surveyed         bool             `json:"surveyed"`        // the features were surveyed: false with --no-close or when the survey failed
	ActiveFeatures   int              `json:"active_features"` // features not abandoned and not closable by sync; 0 unless Surveyed
	Attention        []FeatureReport  `json:"attention"`       // features a person must look at; never null
	Preview          *preview.Preview `json:"preview"`
}

type TokenCheck struct {
	Source     string `json:"source"`
	HTTPStatus int    `json:"http_status"`
}

type UpgradeFile struct {
	Path               string         `json:"path"`
	Status             managed.Status `json:"status"`
	Action             string         `json:"action"` // add | update | remove | unchanged
	ReplacesLocalEdits bool           `json:"replaces_local_edits"`
}

type UpgradeResult struct {
	Public  string           `json:"public"`
	Shadow  string           `json:"shadow"`
	Changed bool             `json:"changed"`
	Files   []UpgradeFile    `json:"files"`
	Commit  string           `json:"commit"`
	Audit   *AuditResult     `json:"audit"`
	Preview *preview.Preview `json:"preview"`
}

type WaitOptions struct {
	// Timeout returns the job still pending after this long; zero waits
	// until CI settles or the gate's own CI budget runs out.
	Timeout time.Duration
	// Events receives the job's events as they happen; nil for none.
	Events func(JobEvent)
}

type WaivedFinding struct {
	leak.Finding
	Reason string `json:"reason"`
}

type WaiversAddOptions struct {
	Feature string
	IDs     []string
	Reason  string
}

type WaiversAddResult struct {
	Feature string           `json:"feature"`
	Waivers []waiver.Waiver  `json:"waivers"`
	Preview *preview.Preview `json:"preview"`
}

type WaiversListResult struct {
	Pair    string          `json:"pair"`
	Waivers []waiver.Waiver `json:"waivers"`
}

type WaiversRevokeResult struct {
	Revoked []waiver.Waiver  `json:"revoked"`
	Preview *preview.Preview `json:"preview"`
}