orchestrate

type AbsorbedConflictAcknowledgementLookup struct {
	ReceiptPath     string
	Receipt         WorktreeMergeReceipt
	Acknowledged    bool
	Acknowledgement WorktreeMergeAbsorbedConflictAcknowledgement
}

type AppliedFileReporter[T any] interface {
	AppliedFiles(T) []string
}

type Assessment[T any] struct {
	Metadata    T
	Applicable  bool
	NeedsChange bool
	Reason      string
}

type CIFailureAnnotation struct {
	Path      string `json:"path" yaml:"path"`
	StartLine int    `json:"start_line" yaml:"start_line"`
	EndLine   int    `json:"end_line,omitempty" yaml:"end_line,omitempty"`
	Message   string `json:"message" yaml:"message"`
}

type CIFailureDetail struct {
	Check       string                `json:"check" yaml:"check"`
	RunURL      string                `json:"run_url,omitempty" yaml:"run_url,omitempty"`
	JobURL      string                `json:"job_url,omitempty" yaml:"job_url,omitempty"`
	Annotations []CIFailureAnnotation `json:"annotations,omitempty" yaml:"annotations,omitempty"`
	Excerpt     string                `json:"excerpt,omitempty" yaml:"excerpt,omitempty"`
	Reason      string                `json:"reason,omitempty" yaml:"reason,omitempty"`
}

type ChangedFile struct {
	Filename string `json:"filename"`
	Status   string `json:"status"`
	Patch    string `json:"patch"`
}

type CheckoutUpdate struct {
	Checkout string
	OldSHA   string
	NewSHA   string
	Cause    string
}

type CreateOutcome string

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

type Handler[T any] interface {
	Inspect(context.Context, string, string, Repository) (Assessment[T], error)
	Apply(context.Context, string, Repository) (T, error)
	ValidatePublishable(context.Context, string, Repository) error
	CommitMessage(Repository) string
	PullRequest(Repository) (title, body string)
}

type HeadCheck struct {
	Name   string
	Bucket string
}

type InPlaceInspector[T any] interface {
	InspectWorkingTree(context.Context, string, Repository) (Assessment[T], error)
}

type LandOutcome string

type LandedCommit struct {
	SourceSHA string `json:"source_sha"`
	LandedSHA string `json:"landed_sha,omitempty"`
	Subject   string `json:"subject"`
	Kept      bool   `json:"kept"`
}

type LaneGuardRequest struct {
	Owner          landinglane.Owner
	TakeOver       bool
	TakeoverReason string
	// StaleAfter overrides how long a prior owner's heartbeat may go
	// unrefreshed before it is taken over automatically. Zero uses
	// landinglane.DefaultStaleAfter.
	StaleAfter time.Duration
}

type MechanicalVerdict struct {
	Mechanical bool
	// Reasons name each file that made the change non-mechanical, and why.
	Reasons []string
	// NonManifest is the subset of Reasons that is just "this is code".
	NonManifest []string
}

type MergeLaneClaim struct {
	// Lane identifies the exclusive (repository, target) merger lane that
	// claimed the branch.
	Lane string `json:"lane"`
	// Target is the branch the lane is draining toward.
	Target string `json:"target"`
	// Status is the receipt's current lifecycle status (see
	// WorktreeMergeStatus), e.g. "prepared" or "checks_pending".
	Status string `json:"status"`
	// ReceiptPath is the exact local receipt backing the claim, so a caller
	// can inspect the full batch (wb worktree merge land <receipt>).
	ReceiptPath string `json:"receipt_path"`
}

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

type Options struct {
	GitHubDir string
	Operation string
	Branch    string
	Ref       string
	Parallel  int
	DryRun    bool
	Resume    bool
	Verify    bool
	Checks    []quality.Check
	Timeout   time.Duration
	Retry     int
	// CheckPollInterval overrides the GitHub-check polling delay. A zero value
	// uses the production default. It is primarily useful for deterministic
	// lifecycle tests.
	CheckPollInterval time.Duration
	Commit            bool
	Push              bool
	PR                bool
	Merge             bool
	// WaitForPRChecks observes exact PR-head checks after opening a pull
	// request, but deliberately does not merge it. It is only valid with PR
	// publication and is intended for validation-only campaigns.
	WaitForPRChecks bool
	// Hold is a set of "owner/name" glob patterns naming repositories whose
	// merge is a human decision. A held repository is changed, verified,
	// pushed, has its pull request opened, and has its exact PR-head checks
	// waited on exactly like any other — and is then left OPEN, even under
	// Merge. It is not a way to skip a repository (that is the caller's own
	// exclusion, applied before this engine sees the repository); it is a way
	// to do all the mechanical work and stop at the one step that needs an
	// owner's judgement, such as a deploy repository the founder gates.
	Hold     []string
	Progress progress.Reporter

	// Prompt is recorded as the originating instruction in the WB manifest
	// journal of every worktree this operation creates, satisfying wb's own
	// commit-admission hook (internal/worktrees.CheckAdmission) — without it,
	// a worktree this engine creates and then commits into is rejected by
	// wb's own pre-commit hook as carrying no record of what it is or who
	// asked for it. Normalize fills in an operation-derived default when
	// empty, so every caller gets a truthful record even if it has nothing
	// more specific to say.
	Prompt string
	// Model, AgentRuntime, Initiator, CLI, and Provider identify who or what
	// asked for this operation, recorded in the same manifest for
	// provenance. Normalize defaults Model to "unknown" when empty, matching
	// the same explicit-over-guessed convention used everywhere else a
	// child model identity is recorded (see internal/worktrees.WorkLogOptions).
	Model        string
	AgentRuntime string
	Initiator    string
	CLI          string
	Provider     string
	// DependencyCampaign marks worktrees created by dependency set/bump
	// campaigns. Their supersession receipts require exact dependency proof.
	DependencyCampaign bool
	// FetchMemo, when non-nil, memoizes this run's completed origin fetches
	// and receives touch-invalidation from the push, PR-open, and merge
	// stages (see FetchMemo). Only a campaign loop that alternates fleet-wide
	// discovery and mutation over the same repositories within one process —
	// wb deps bump with --fetch-cache — threads one memo through every
	// discovery and wave lifecycle it runs. Every other caller leaves it nil
	// and keeps the unconditional engine fetch: for deps set --fleet there is
	// no prior discovery, so that fetch is the operation's only origin read
	// and must never be skipped.
	FetchMemo *FetchMemo
	// FetchMemoDiscovery marks this lifecycle as read-only graph discovery,
	// which is the ONLY context allowed to consume the memo: EnsureCanonical
	// may then skip a fresh, untouched memoized fetch. The mutation engine
	// leaves it false even when FetchMemo is threaded, so a wave's branch
	// base is always cut from a fetch completed moments before — never from a
	// snapshot up to one full discovery pass old, which would interact badly
	// with strict up-to-date branch protection and exact-head merges. The
	// engine's own fetches still refresh the memo, and its publication
	// stages still invalidate through it.
	FetchMemoDiscovery bool
}

type PullRequestCreateOptions struct {
	// Worktree is a linked worktree path or a task name. Empty resolves to
	// the current directory.
	Worktree     string
	ProjectsRoot string
	Title        string
	// Body is literal pull-request body text, as `gh pr create --body` takes
	// it. Mutually exclusive with BodyFile; the caller validates that.
	Body     string
	BodyFile string
	Draft    bool
	// Base overrides the pull request's target branch. Empty uses the
	// worktree's own recorded base.
	Base string
	// Closes lists issue numbers this pull request closes; one "Closes #N"
	// line per issue is written at the top of the body (#615). Never
	// populated from the task's prompt automatically — see
	// SuggestClosesFromPrompt, which the caller decides whether to act on.
	Closes []int

	// AutoMerge arms GitHub auto-merge immediately after the pull request is
	// created or adopted, under the same authority `wb pr land` requires to
	// arm it: a mechanical diff, or a non-mechanical one with ApprovedBy, and
	// a target whose policy AllowUnfenced does not have to widen.
	AutoMerge     bool
	ApprovedBy    string
	AllowUnfenced bool
	MergeMethod   string
	// Lane optionally names the acquiring WB session for the same
	// landing-lane guard `wb pr land` acquires around arming; see
	// LaneGuardRequest. A zero value skips the guard, exactly as it does for
	// LandPullRequest. Only meaningful with AutoMerge; --land threads its own
	// Lane through LandOptions instead.
	Lane LaneGuardRequest

	// CommitStaged commits exactly the worktree's index. It refuses when
	// nothing is staged. CommitAll runs `git add -A` first (respecting
	// .gitignore, and refusing any path that looks like a secret), then
	// commits everything. They are mutually exclusive; the caller validates
	// that. Message is required with either one and is used verbatim.
	// Add commits exactly the named paths: `git add -- <paths>`, then
	// `git commit -m Message -- <paths>`, so anything else already staged is
	// not included. It is a third commit mode, mutually exclusive with
	// CommitStaged and CommitAll; the caller validates that.
	Add          []string
	CommitStaged bool
	CommitAll    bool
	Message      string

	// Land lands the pull request in-process through the existing
	// `LandPullRequest`, using LandOptions as a template: Repository and
	// PullRequest are filled in here once both are known. `--land` implies
	// arming, the way `wb pr land` itself does, so AutoMerge is not armed
	// separately when Land is set.
	Land        bool
	LandOptions *PullRequestLandOptions

	// LinkPreflight runs immediately before arming auto-merge or landing,
	// exactly as `wb pr land` runs `refuseLinkedRepositoryWorktrees` before
	// its own GitHub calls. It lives in cmd/wb, not here, so it is injected
	// rather than imported: internal/orchestrate must not depend on cmd/wb.
	LinkPreflight func(repository string) error

	Timeout time.Duration
	Retry   int

	// Events receives one structured record per invocation, whatever the
	// outcome. A nil appender discards. EventsForRepository, when set,
	// overrides it once the repository is resolved: this verb's own
	// repository is not known until the worktree's manifest is read, unlike
	// `wb pr land`, which receives it as its own CLI argument up front, so
	// cmd/wb cannot resolve the repository-scoped stream ahead of the call
	// the way it does for `wb pr land`. --land also uses it to give the
	// nested `LandPullRequest` call the same repository-scoped stream
	// `wb pr land` itself would have used.
	Events              streams.EventAppender
	Stream              string
	EventsForRepository func(repository string) (streams.EventAppender, string)
}

type PullRequestCreateResult struct {
	SchemaVersion     int           `json:"v"`
	Verb              string        `json:"verb"`
	Outcome           CreateOutcome `json:"outcome"`
	RefusalCode       string        `json:"refusal_code,omitempty"`
	SanctionedCommand string        `json:"sanctioned_command,omitempty"`
	Reason            string        `json:"reason,omitempty"`

	Repository  string `json:"repository,omitempty"`
	PullRequest int    `json:"pull_request,omitempty"`
	URL         string `json:"url,omitempty"`
	Title       string `json:"title,omitempty"`
	HeadRef     string `json:"head_ref,omitempty"`
	HeadSHA     string `json:"head_sha,omitempty"`
	BaseRef     string `json:"base_ref,omitempty"`
	// Adopted records that an already-open pull request for this branch was
	// reused rather than a new one created.
	Adopted bool `json:"adopted,omitempty"`

	Mechanical bool   `json:"mechanical"`
	ApprovedBy string `json:"approved_by,omitempty"`

	AutoMergeArmed  bool   `json:"auto_merge_armed,omitempty"`
	AutoMergeReason string `json:"auto_merge_not_armed_reason,omitempty"`

	// NextCommand is the exact follow-up invocation: `wb pr land` unless
	// AutoMerge was requested, in which case it is `wb wait pr`.
	NextCommand string `json:"next_command,omitempty"`

	// Task and ClaimID identify the durable Work Log claim the pull request
	// was bound to, when binding succeeded.
	Task    string `json:"task,omitempty"`
	ClaimID string `json:"claim_id,omitempty"`

	// CommittedPaths lists every path a requested --commit-staged/--commit-all
	// committed, in the order `git diff-tree` reports them.
	CommittedPaths []string `json:"committed_paths,omitempty"`

	// LandResult is populated when Land was requested: the full receipt of the
	// in-process `LandPullRequest` call this invocation's own Outcome mirrors.
	LandResult *PullRequestLandResult `json:"land_result,omitempty"`

	Evidence map[string]string `json:"evidence,omitempty"`
}

type PullRequestLandOptions struct {
	Repository   string
	PullRequest  string
	ProjectsRoot string
	// Keep retains the task's worktrees and claims. Cleanup is the default
	// precisely because the opt-in form was never passed.
	Keep bool
	// ApprovedBy records the review that authorized a non-mechanical change.
	// It is one of: an existing file path or a pull-request comment URL
	// (unchanged, back-compatible); the literal "ci"; or a reviewer identity
	// `{model}[@{harness}[@{session}]]`, which requires ReviewComment or
	// ReviewCommentFile and causes WB to post the review as a PR comment and
	// bind it to the exact head it reviewed (#604, #586).
	ApprovedBy string
	// ReviewComment is the review text for the identity form of ApprovedBy.
	// Mutually exclusive with ReviewCommentFile; the caller validates that.
	ReviewComment string
	// ReviewCommentFile is a path to the review text for the identity form
	// of ApprovedBy.
	ReviewCommentFile string
	// MergeMethod is merge by default: preserve commits and the reviewed PR boundary.
	MergeMethod string
	// MergeMethodExplicit distinguishes an operator-selected method from the merge
	// default. KeepCommits requires an explicitly selected squash hybrid.
	MergeMethodExplicit bool
	// Subject overrides the explicit squash commit subject. The default is the pull
	// request's own title, which is the thing GitHub will otherwise replace
	// with the branch's first commit subject.
	Subject string
	// KeepCommits names source commits that must land as their own commits
	// instead of being folded into the aggregate. Reason is mandatory with it:
	// the exception has to be justified in the history it creates.
	KeepCommits []string
	Reason      string
	// BuildCommand overrides the per-kept-commit build guard. Empty uses the
	// repository's own target, which is `go build ./...` for a Go module.
	BuildCommand []string
	// AllowUnfenced lands on observed checks alone, where the target branch has
	// no server-enforced strict up-to-date policy. Without such a fence, green
	// checks prove the head was green, not that it is still green against the
	// target the merge will use, so this is an explicit widening rather than a
	// default — and the receipt records that it was used.
	AllowUnfenced bool
	// Slice is the total foreground wait budget retained under its historical
	// name for API compatibility. A landing may outlive the bounded CI waiter:
	// WB divides this budget into exact-identity observation slices instead of
	// rejecting an otherwise valid long-running landing.
	Slice             time.Duration
	CheckPollInterval time.Duration
	Progress          func(PullRequestWaitProgress)
	OperationProgress progress.Reporter
	// Events receives one structured record per invocation, whatever the
	// outcome. A refusal is the most useful event of all — it is the one that
	// says a verb was reached and declined — so `--keep` and every refusal
	// write one too. A nil appender discards.
	Events streams.EventAppender
	// Stream names the stream this landing belongs to, when it belongs to one.
	Stream string
	Now    func() time.Time
	// NoUpdateBranch keeps the historical behaviour of refusing a candidate
	// that is behind the target instead of bringing it up to date. The default
	// updates, because a target with a strict up-to-date policy puts every
	// candidate behind whenever anything else lands, and refusing then costs a
	// manual merge plus a full fresh CI cycle.
	NoUpdateBranch bool
	// NoAutoMerge keeps the historical behaviour of returning checks-pending
	// when the wait budget runs out. The default arms GitHub auto-merge
	// instead, so a complete change is not left stranded on whoever remembers
	// it next.
	//
	// The arming is deliberately not withdrawn when checks fail. CI is the
	// gate: whoever pushes a fix is responsible for it, the required checks
	// re-run against exactly what they pushed, and the merge happens only if
	// those pass. A review that must not be skippable belongs in the workflow,
	// where it runs on every push and nobody can decline to re-request it —
	// not in an approval recorded once against a head that no longer exists.
	NoAutoMerge bool
	// Lane optionally names the acquiring session for the landing-lane
	// ownership guard (see LaneGuardRequest in internal/orchestrate). Left
	// zero, no guard runs — existing direct callers are unaffected.
	Lane            LaneGuardRequest
	CheckoutUpdated func(context.Context, CheckoutUpdate)
	// contains filtered or unexported fields
}

type PullRequestLandResult struct {
	SchemaVersion int         `json:"v"`
	Verb          string      `json:"verb"`
	Outcome       LandOutcome `json:"outcome"`
	RefusalCode   string      `json:"refusal_code,omitempty"`
	// SanctionedCommand is the exact command that satisfies the guard that
	// fired. A refusal an agent cannot resolve becomes a hand-written
	// workaround, which is how the cleanup path was bypassed in the first place.
	SanctionedCommand string `json:"sanctioned_command,omitempty"`
	// AutoMergeArmed records that this invocation armed GitHub auto-merge. It
	// says nothing about who performed the merge: evidence "merged_by" is set
	// when GitHub did. When the invocation ends before the merge, GitHub lands
	// the change without WB, and the worktree is still the caller's to retire.
	AutoMergeArmed bool   `json:"auto_merge_armed,omitempty"`
	Reason         string `json:"reason,omitempty"`

	Repository  string `json:"repository"`
	PullRequest int    `json:"pull_request"`
	URL         string `json:"url,omitempty"`
	Title       string `json:"title,omitempty"`
	HeadRef     string `json:"head_ref,omitempty"`
	HeadSHA     string `json:"head_sha,omitempty"`
	BaseRef     string `json:"base_ref,omitempty"`
	MergeSHA    string `json:"merge_sha,omitempty"`
	Subject     string `json:"subject,omitempty"`

	// Mechanical records the diff-derived classification and the files it was
	// derived from, so a reader can check the judgement rather than trust it.
	Mechanical   bool     `json:"mechanical"`
	ChangedFiles []string `json:"changed_files,omitempty"`
	NonManifest  []string `json:"non_manifest_files,omitempty"`
	ApprovedBy   string   `json:"approved_by,omitempty"`
	// Reviewer, ReviewedHeadSHA, ReviewDigest, ReviewCommentURL, and
	// SelfReview are the #604/#586 receipt fields: the full reviewer
	// identity triple, the exact head it reviewed, a digest of the review
	// text, the posted comment's URL (identity form only), and whether the
	// reviewer identity fully matches this session's own (see
	// currentSessionIdentity).
	Reviewer         string `json:"reviewer,omitempty"`
	ReviewedHeadSHA  string `json:"reviewed_head,omitempty"`
	ReviewDigest     string `json:"review_digest,omitempty"`
	ReviewCommentURL string `json:"review_comment_url,omitempty"`
	SelfReview       bool   `json:"self_review,omitempty"`
	// ReviewBound is nil (omitted from JSON) when no review applied at all
	// (a mechanical landing, round 3 minor 7). Once a review did apply, it
	// is a pointer to false when the recorded review named no commit to
	// bind to, or when the binding could not be verified (#586's
	// warn-still-land design, founder-decided 2026-09-18) — the landing
	// proceeds either way, this is never a refusal — but Evidence["review"]
	// carries the informational finding so the gap is visible rather than
	// silent. It is a pointer to true only once the binding is positively
	// confirmed.
	ReviewBound *bool `json:"review_bound,omitempty"`
	// Closes lists the issues GitHub's own closingIssuesReferences reports
	// this landing closes (#615). Empty is reported as the informational
	// "no linked issue" finding in Evidence["closes"], never a refusal.
	Closes []int `json:"closes,omitempty"`

	Checks *PullRequestWaitResult `json:"checks,omitempty"`

	BranchDeleted bool   `json:"branch_deleted"`
	LandingOnBase bool   `json:"landing_on_base"`
	CanonicalSync string `json:"canonical_sync,omitempty"`
	// LocalSync records the outcome of fast-forwarding the local WB worktree
	// (if any) after a server-side update-branch, or the reason it was left
	// alone (#611). Empty when no worktree holds the branch.
	LocalSync string `json:"local_sync,omitempty"`
	// Commits pairs every source commit with the commit that landed it, and
	// marks the ones kept separate. GitHub's rebase merge rewrites the SHAs, so
	// after landing this pairing is the only way back to the originals.
	Commits        []LandedCommit `json:"commits,omitempty"`
	KeptCommits    []string       `json:"kept_commits,omitempty"`
	KeepReason     string         `json:"keep_reason,omitempty"`
	CleanedTasks   []string       `json:"cleaned_tasks,omitempty"`
	CleanupReports []string       `json:"cleanup_reports,omitempty"`
	Kept           bool           `json:"kept"`

	// ManualEquivalent is the ordered list of calls a caller would otherwise
	// have made. SavedToolCalls is that count minus one — the one call they
	// made instead.
	ManualEquivalent    []string `json:"manual_equivalent"`
	SavedToolCalls      int      `json:"saved_tool_calls"`
	SavedTokensEstimate int      `json:"saved_tokens_est"`
	// AbsorbedPolls counts the check observations the verb waited through.
	// Absorbing a poll loop is the largest single saving it makes.
	AbsorbedPolls int `json:"absorbed_polls"`

	Evidence map[string]string `json:"evidence,omitempty"`

	// LaneOwner is the landing-lane record this landing acquired, when the
	// caller populated Lane. It is nil when no guard ran.
	LaneOwner *landinglane.Record `json:"lane_owner,omitempty"`
}

type PullRequestView struct {
	Number         int        `json:"number"`
	State          string     `json:"state"`
	Draft          bool       `json:"draft"`
	Locked         bool       `json:"locked"`
	Title          string     `json:"title"`
	Body           string     `json:"body"`
	HTMLURL        string     `json:"html_url"`
	Merged         bool       `json:"merged"`
	MergedAt       *time.Time `json:"merged_at"`
	MergeCommitSHA string     `json:"merge_commit_sha"`
	// Mergeable is nil while GitHub is still computing the merge state. A nil
	// is not a "no": it is "ask again", and a verb must not read it as either
	// mergeable or conflicted.
	Mergeable      *bool  `json:"mergeable"`
	MergeableState string `json:"mergeable_state"`
	Head           struct {
		Ref  string `json:"ref"`
		SHA  string `json:"sha"`
		Repo *struct {
			FullName string `json:"full_name"`
		} `json:"repo"`
	} `json:"head"`
	Base struct {
		Ref  string `json:"ref"`
		SHA  string `json:"sha"`
		Repo *struct {
			FullName string `json:"full_name"`
		} `json:"repo"`
	} `json:"base"`
}

type PullRequestWaitOptions struct {
	Repository  string
	PullRequest string
	Target      string
	Head        string
	// AllowTargetDescendant is only for post-landing target CI: the exact
	// landed Head must remain an ancestor of the observed target. Pre-landing
	// candidate and pull-request waits retain exact target-head freshness.
	AllowTargetDescendant bool
	// AllowUnfenced permits a validation-only PR check receipt when the target
	// branch has no server-enforced strict freshness fence. Merge callers leave
	// this false; it is an explicit opt-in for wait-only validation.
	AllowUnfenced     bool
	Slice             time.Duration
	CheckPollInterval time.Duration
	// StableRereadDelay overrides the shortened wait before the confirming
	// reread of a checks-bearing terminal observation. A zero value uses
	// DefaultStableRereadDelay, and the delay never exceeds
	// CheckPollInterval. The no-applicable-checks receipt and any reread
	// after fingerprint churn always wait the full CheckPollInterval.
	StableRereadDelay time.Duration
	// Progress receives completed GitHub observations. It is diagnostic only;
	// callers must use the returned result as the authoritative receipt.
	Progress          func(PullRequestWaitProgress)
	OperationProgress progress.Reporter
}

type PullRequestWaitProgress struct {
	Observation int
	Result      PullRequestWaitResult
	NextPoll    time.Duration
}

type PullRequestWaitResult struct {
	Status                     PullRequestWaitStatus `json:"status" yaml:"status"`
	Repository                 string                `json:"repository" yaml:"repository"`
	PullRequest                string                `json:"pull_request,omitempty" yaml:"pull_request,omitempty"`
	Target                     string                `json:"target" yaml:"target"`
	Head                       string                `json:"head" yaml:"head"`
	ObservedHead               string                `json:"observed_head,omitempty" yaml:"observed_head,omitempty"`
	ObservedTargetHead         string                `json:"observed_target_head,omitempty" yaml:"observed_target_head,omitempty"`
	CandidateContainsTarget    bool                  `json:"candidate_contains_target,omitempty" yaml:"candidate_contains_target,omitempty"`
	TargetContainsHead         bool                  `json:"target_contains_head,omitempty" yaml:"target_contains_head,omitempty"`
	TargetFreshnessAuthority   string                `json:"target_freshness_authority,omitempty" yaml:"target_freshness_authority,omitempty"`
	Checks                     []RemoteCheck         `json:"checks,omitempty" yaml:"checks,omitempty"`
	FailureDetails             []CIFailureDetail     `json:"failure_details,omitempty" yaml:"failure_details,omitempty"`
	RequiredChecks             []RequiredRemoteCheck `json:"required_checks,omitempty" yaml:"required_checks,omitempty"`
	RequiredChecksAuthority    string                `json:"required_checks_authority,omitempty" yaml:"required_checks_authority,omitempty"`
	PolicyAuthorityUnavailable string                `json:"policy_authority_unavailable,omitempty" yaml:"policy_authority_unavailable,omitempty"`
	UnfencedValidation         bool                  `json:"unfenced_validation,omitempty" yaml:"unfenced_validation,omitempty"`
	StableObservations         int                   `json:"stable_observations" yaml:"stable_observations"`
	Reason                     string                `json:"reason,omitempty" yaml:"reason,omitempty"`
	// Evidence carries auxiliary receipt facts that are not part of the wait
	// outcome itself. "github_read_retries" mirrors the same key on
	// PullRequestLandResult: the count and last cause of in-process transient
	// GitHub read recoveries absorbed while producing this result.
	Evidence map[string]string `json:"evidence,omitempty" yaml:"evidence,omitempty"`
}

type PullRequestWaitStatus string

type RemoteCheck struct {
	Name   string `json:"name" yaml:"name"`
	Bucket string `json:"bucket" yaml:"bucket"`
	// Conclusion is the raw GitHub check-run/workflow-run conclusion (e.g.
	// "success", "skipped", "neutral", "failure"), kept alongside Bucket so a
	// strict deferral-satisfaction check (sneat-dev/wb#591 red-team finding
	// X2) can tell an actually-executed pass ("success") apart from a check
	// that never ran ("skipped" or "neutral") even though checkRunBucket
	// buckets both "success" and "neutral" the same, as an ordinary "pass"
	// (only "skipped" gets its own "skipping" bucket) for the overall
	// pass/fail loop. Empty for a commit-status-derived check, which has no
	// conclusion.
	Conclusion string `json:"conclusion,omitempty" yaml:"conclusion,omitempty"`
	Link       string `json:"link,omitempty" yaml:"link,omitempty"`
	AppID      int64  `json:"app_id,omitempty" yaml:"app_id,omitempty"`
	CheckRunID int64  `json:"check_run_id,omitempty" yaml:"check_run_id,omitempty"`
}

type Repository struct {
	Slug     string
	Path     string
	CloneURL string
	Archived bool
}

type RequiredRemoteCheck struct {
	Name          string `json:"name" yaml:"name"`
	IntegrationID int64  `json:"integration_id,omitempty" yaml:"integration_id,omitempty"`
}

type ResolvedBase struct {
	// Ref is the short branch name (no "origin/" prefix).
	Ref string
	// Fallback is true when the operation's configured ref did not exist for
	// this repository and Ref instead names its actual origin/HEAD default
	// branch. Nothing about this is silent: every caller that receives a
	// Fallback result is expected to surface it in its own report.
	Fallback bool
}

type Result[T any] struct {
	Repository    string
	CanonicalDir  string
	WorktreeDir   string
	Branch        string
	Ref           string
	Status        string
	Reason        string
	Metadata      T
	ChangedFiles  []string
	Verifications []quality.VerificationEntry
	Commit        string
	Pushed        bool
	PR            string
	Checks        []RemoteCheck
	Merged        bool
	// Held records that Options.Hold matched this repository, so its pull
	// request was deliberately left open for a human decision rather than
	// merged. It is never inferred from a failure.
	Held bool
}

type ReviewerIdentity struct {
	Model   string `json:"model"`
	Harness string `json:"harness,omitempty"`
	Session string `json:"session,omitempty"`
}

type SourceCommit struct {
	SHA     string `json:"sha"`
	Subject string `json:"subject"`
	Body    string `json:"body,omitempty"`
}

type WorktreeMergeAbsorbedConflictAcknowledgement = mergeack.Acknowledgement

type WorktreeMergeAbsorbedConflictAcknowledgementOptions struct {
	ProjectsRoot string
	Receipt      string
	Apply        bool
	Actor        string
	Reason       string
	// DerivedPaths audits an operator exclusion for derived/generated files
	// (repo-relative, repeatable) -- each must exist on the freshly fetched
	// target and match the built-in derived-index allowlist
	// (isAbsorbedConflictDerivedPathAllowed), or the whole call refuses.
	DerivedPaths []string
}

type WorktreeMergeAbsorbedConflictPathProof = mergeack.PathProof

type WorktreeMergeAbsorbedConflictSourceProof = mergeack.SourceProof

type WorktreeMergeCandidate struct {
	Task     string `json:"task"`
	Worktree string `json:"worktree"`
	Branch   string `json:"branch"`
	SHA      string `json:"sha"`
}

type WorktreeMergeConflictCandidateAdvance struct {
	SchemaVersion        int                    `json:"schema_version"`
	ID                   string                 `json:"id"`
	Status               string                 `json:"status"`
	ReceiptPath          string                 `json:"receipt_path"`
	AcknowledgementPath  string                 `json:"acknowledgement_path"`
	ReceiptSHA256        string                 `json:"receipt_sha256"`
	ReceiptID            string                 `json:"receipt_id"`
	Lane                 string                 `json:"lane"`
	Repository           string                 `json:"repository"`
	Target               string                 `json:"target"`
	ReceiptTargetSHA     string                 `json:"receipt_target_sha"`
	CurrentTargetSHA     string                 `json:"current_target_sha"`
	OriginalCandidate    WorktreeMergeCandidate `json:"original_candidate"`
	AdvancedCandidateSHA string                 `json:"advanced_candidate_sha"`
	ClaimBaseSHA         string                 `json:"claim_base_sha"`
	Sources              []WorktreeMergeSource  `json:"sources"`
	RecordedAt           time.Time              `json:"recorded_at"`
}

type WorktreeMergeConflictCandidateRefresh struct {
	Status                      string                                   `json:"status"`
	ReceiptPath                 string                                   `json:"receipt_path"`
	ReceiptSHA256               string                                   `json:"receipt_sha256"`
	ImmutableClaimSHA256        string                                   `json:"immutable_claim_sha256"`
	CurrentTargetSHA            string                                   `json:"current_target_sha"`
	ObservedCandidateDescendant string                                   `json:"observed_candidate_descendant_sha,omitempty"`
	Sources                     []WorktreeMergeSource                    `json:"sources"`
	RequiredRoots               []WorktreeMergeValidationFailureSealRoot `json:"required_roots"`
	Candidate                   WorktreeMergeCandidate                   `json:"candidate"`
	Actor                       string                                   `json:"actor"`
	Reason                      string                                   `json:"reason"`
}

type WorktreeMergeConflictCandidateRefreshOptions struct {
	ProjectsRoot, Receipt, ExpectedReceiptSHA256, ExpectedImmutableClaimSHA256, ExpectedCurrentTargetSHA string
	Sources, ExpectedSourceSHAs                                                                          []string
	Apply                                                                                                bool
	Actor, Reason                                                                                        string
	Model, AgentRuntime, AgentID, Initiator, CLI, Provider                                               string
	SessionRequired                                                                                      bool
	Timeout                                                                                              time.Duration
	Retry                                                                                                int
	Progress                                                                                             progress.Reporter
}

type WorktreeMergeFinding struct {
	Code    string   `json:"code"`
	Message string   `json:"message"`
	Checks  []string `json:"checks,omitempty"`
}

type WorktreeMergeForwardRepairReceipt struct {
	Status       WorktreeMergeStatus   `json:"status"`
	TargetSHA    string                `json:"target_sha"`
	CandidateSHA string                `json:"candidate_sha"`
	LandingSHA   string                `json:"landing_sha"`
	PullRequest  string                `json:"pull_request,omitempty"`
	Checks       PullRequestWaitResult `json:"checks"`
	Failure      string                `json:"failure"`
}

type WorktreeMergeHostLoadAdmission struct {
	Load       float64 `json:"load"`
	Floor      float64 `json:"floor"`
	Overridden bool    `json:"overridden"`
	// SkippedReason names why admission was disabled for this check (never
	// evaluated against Load): "env" (WB_ADMISSION_LOAD_FLOOR<=0), "ci"
	// (CI/GITHUB_ACTIONS declared), or "config" (wb.yaml admission.load_floor:
	// 0). Empty means admission was active — see internal/hostload.Resolve.
	SkippedReason string    `json:"skipped_reason,omitempty"`
	CheckedAt     time.Time `json:"checked_at"`
}

type WorktreeMergeLandOptions struct {
	ProjectsRoot  string
	Receipt       string
	Route         WorktreeMergeRoute
	Cleanup       bool
	AllowUnfenced bool
	OnFailure     string
	Timeout       time.Duration
	Retry         int
	// ValidateLocally forces the old unconditional behavior: local candidate
	// validation always runs, even when this call resolves the pull-request
	// route and its target's authoritative required-check policy would
	// otherwise be eligible for a validation deferral. See
	// worktreeMergeValidationDeferralEligible and sneat-dev/wb#591.
	ValidateLocally bool
	// PrepareTimeout bounds recovery of an interrupted preparing receipt.
	// It does not apply after the candidate has reached prepared state.
	PrepareTimeout time.Duration
	// CheckTimeout and ShardAttemptTimeout override the validation limits stored
	// by an interrupted preparing receipt. The effective limits are persisted
	// before validation so a later retry observes the same policy.
	CheckTimeout        time.Duration
	ShardAttemptTimeout time.Duration
	CheckPollInterval   time.Duration
	Progress            progress.Reporter
	ProgressRequested   bool
	// StopBeforeMerge is the explicit PR-only handoff mode. It validates the
	// preserved candidate and proves the remote open PR identity, then returns
	// before CI observation or any merge operation. It is deliberately not
	// persisted as future landing intent: a bare resume is how the merger takes
	// over from the published handoff.
	StopBeforeMerge bool
	// HostLoadAdmission is the host-load admission check cmd/wb ran, if any,
	// before calling Land/ResumeWorktreeMerge. Nil means the caller decided no
	// check was needed for this step (e.g. it neither validates nor pushes).
	// When set it is copied onto the receipt so the override is provable from
	// the receipt itself, not only from the caller's own log.
	HostLoadAdmission *WorktreeMergeHostLoadAdmission
	// Lane optionally names the acquiring session for the landing-lane
	// ownership guard (see LaneGuardRequest). Left zero, no guard runs.
	Lane LaneGuardRequest
	// CheckoutUpdated is called only after the checked-out canonical target
	// has moved and the exact landed commit is proven reachable. Nil discards.
	CheckoutUpdated func(context.Context, CheckoutUpdate)
}

type WorktreeMergeLandedFailureAcknowledgement struct {
	SchemaVersion       int                   `json:"schema_version"`
	ID                  string                `json:"id"`
	Status              string                `json:"status"`
	ReceiptPath         string                `json:"receipt_path"`
	AcknowledgementPath string                `json:"acknowledgement_path"`
	ReceiptID           string                `json:"receipt_id"`
	ReceiptStatus       WorktreeMergeStatus   `json:"receipt_status"`
	Lane                string                `json:"lane"`
	Repository          string                `json:"repository"`
	Target              string                `json:"target"`
	ReceiptTargetSHA    string                `json:"receipt_target_sha"`
	ReceiptLandingSHA   string                `json:"receipt_landing_sha,omitempty"`
	CurrentTargetSHA    string                `json:"current_target_sha"`
	CandidateSHA        string                `json:"candidate_sha"`
	ClaimBaseSHA        string                `json:"claim_base_sha"`
	CandidateWorktree   string                `json:"candidate_worktree"`
	CandidateBranch     string                `json:"candidate_branch"`
	Sources             []WorktreeMergeSource `json:"sources"`
	Actor               string                `json:"actor"`
	Reason              string                `json:"reason"`
	RecordedAt          time.Time             `json:"recorded_at"`
}

type WorktreeMergeLandedFailureAcknowledgementOptions struct {
	ProjectsRoot string
	Receipt      string
	Apply        bool
	Actor        string
	Reason       string
}

type WorktreeMergeLegacyConflictIdentity struct {
	SchemaVersion       int                    `json:"schema_version"`
	ID                  string                 `json:"id"`
	Status              string                 `json:"status"`
	ReceiptPath         string                 `json:"receipt_path"`
	AcknowledgementPath string                 `json:"acknowledgement_path"`
	ReceiptSHA256       string                 `json:"receipt_sha256"`
	ReceiptID           string                 `json:"receipt_id"`
	Lane                string                 `json:"lane"`
	Repository          string                 `json:"repository"`
	Target              string                 `json:"target"`
	ReceiptTargetSHA    string                 `json:"receipt_target_sha"`
	CurrentTargetSHA    string                 `json:"current_target_sha"`
	Candidate           WorktreeMergeCandidate `json:"candidate"`
	ClaimBaseSHA        string                 `json:"claim_base_sha"`
	Sources             []WorktreeMergeSource  `json:"sources"`
	Actor               string                 `json:"actor"`
	Reason              string                 `json:"reason"`
	RecordedAt          time.Time              `json:"recorded_at"`
}

type WorktreeMergeLegacyValidationFailureIdentity struct {
	SchemaVersion       int                    `json:"schema_version"`
	ID                  string                 `json:"id"`
	Status              string                 `json:"status"`
	ReceiptPath         string                 `json:"receipt_path"`
	AcknowledgementPath string                 `json:"acknowledgement_path"`
	ReceiptSHA256       string                 `json:"receipt_sha256"`
	ReceiptID           string                 `json:"receipt_id"`
	Lane                string                 `json:"lane"`
	Repository          string                 `json:"repository"`
	Target              string                 `json:"target"`
	ReceiptTargetSHA    string                 `json:"receipt_target_sha"`
	CurrentTargetSHA    string                 `json:"current_target_sha"`
	Candidate           WorktreeMergeCandidate `json:"candidate"`
	ClaimBaseSHA        string                 `json:"claim_base_sha"`
	Sources             []WorktreeMergeSource  `json:"sources"`
	Actor               string                 `json:"actor"`
	Reason              string                 `json:"reason"`
	RecordedAt          time.Time              `json:"recorded_at"`
}

type WorktreeMergeMissingCleanupAcknowledgement struct {
	SchemaVersion       int                                    `json:"schema_version"`
	ID                  string                                 `json:"id"`
	Status              string                                 `json:"status"`
	ReceiptPath         string                                 `json:"receipt_path"`
	AcknowledgementPath string                                 `json:"acknowledgement_path"`
	ReceiptSHA256       string                                 `json:"receipt_sha256"`
	ReceiptID           string                                 `json:"receipt_id"`
	Lane                string                                 `json:"lane"`
	Repository          string                                 `json:"repository"`
	Target              string                                 `json:"target"`
	LandingSHA          string                                 `json:"landing_sha"`
	CurrentTargetSHA    string                                 `json:"current_target_sha"`
	Assets              []worktrees.TerminalWorkLogExpectation `json:"absent_assets"`
	Actor               string                                 `json:"actor"`
	Reason              string                                 `json:"reason"`
	RecordedAt          time.Time                              `json:"recorded_at"`
}

type WorktreeMergeMissingCleanupAcknowledgementOptions struct {
	ProjectsRoot string
	Receipt      string
	Apply        bool
	Actor        string
	Reason       string
}

type WorktreeMergePhase string

type WorktreeMergePrepareOptions struct {
	ProjectsRoot string
	Sources      []string
	Target       string
	Model        string
	AgentRuntime string
	AgentID      string
	Initiator    string
	CLI          string
	Provider     string
	Timeout      time.Duration
	Retry        int
	// Route lets a caller decide the merge route before preparing (and
	// therefore before deciding whether local validation may be deferred to
	// the pull-request route's authoritative CI). Empty resolves as auto, the
	// same default LandWorktreeMerge uses.
	Route WorktreeMergeRoute
	// ValidateLocally forces local candidate validation during prepare even
	// when the pull-request route would otherwise be eligible to defer it.
	ValidateLocally bool
	// PrepareTimeout bounds one prepare invocation. Zero leaves preparation
	// unbounded apart from the existing command timeout.
	PrepareTimeout time.Duration
	// CheckTimeout bounds one logical candidate or baseline validation check.
	// Zero retains the existing per-command behavior.
	CheckTimeout time.Duration
	// ShardAttemptTimeout bounds one process-isolated Go test shard attempt.
	// Zero retains the existing --timeout behavior for shard attempts.
	ShardAttemptTimeout time.Duration
	Progress            progress.Reporter
	ProgressRequested   bool
	// RebatchReceipt is an immutable, still-unlanded prepared or exact published
	// pending/failed-check receipt whose sources are replaced additively.
	RebatchReceipt string
	// HostLoadAdmission is the host-load admission check cmd/wb ran before
	// calling PrepareWorktreeMerge, if any. It is copied onto the new receipt
	// so the override is provable from the receipt itself.
	HostLoadAdmission *WorktreeMergeHostLoadAdmission
	// RequireHostLoadAdmission is cmd/wb's lazy fallback for the gap round
	// 4's minor 2 closes: its combined `wb worktree land`/`wb land` command
	// skips the up-front host-load admission check whenever a cheap
	// PeekWorktreeMergeValidationDeferral call predicts the resolved
	// validation plan will defer to CI (so no local CPU work is coming,
	// and the check would gate nothing). If a transient GitHub read makes
	// the ACTUAL resolve here disagree with that prediction and fall back
	// to local validation after all, HostLoadAdmission is still nil — the
	// up-front check never ran — and running CPU-heavy validation ungated
	// is exactly the saturated-host incident admission exists to prevent.
	// When set, this is invoked exactly once, only when the resolved plan
	// does not defer and HostLoadAdmission is still nil; a non-nil error
	// stops the prepare before validation ever runs, exactly as the
	// up-front check would have. Nil (every other caller) changes nothing.
	RequireHostLoadAdmission func() (*WorktreeMergeHostLoadAdmission, error)
	// Lane optionally names the acquiring session for the landing-lane
	// ownership guard (see LaneGuardRequest). Left zero, no guard runs.
	Lane LaneGuardRequest
}

type WorktreeMergePreparedRebatch struct {
	SchemaVersion          int                    `json:"schema_version"`
	ID                     string                 `json:"id"`
	Status                 string                 `json:"status"`
	ReceiptPath            string                 `json:"receipt_path"`
	AcknowledgementPath    string                 `json:"acknowledgement_path"`
	ReceiptID              string                 `json:"receipt_id"`
	ReceiptSHA256          string                 `json:"receipt_sha256"`
	ReceiptStatus          WorktreeMergeStatus    `json:"receipt_status"`
	Lane                   string                 `json:"lane"`
	Repository             string                 `json:"repository"`
	Target                 string                 `json:"target"`
	ReceiptTargetSHA       string                 `json:"receipt_target_sha"`
	CurrentTargetSHA       string                 `json:"current_target_sha"`
	OriginalCandidate      WorktreeMergeCandidate `json:"original_candidate"`
	OriginalSources        []WorktreeMergeSource  `json:"original_sources"`
	ReplacementReceiptPath string                 `json:"replacement_receipt_path"`
	Replacement            WorktreeMergeCandidate `json:"replacement"`
	Sources                []WorktreeMergeSource  `json:"sources"`
	RecordedAt             time.Time              `json:"recorded_at"`
	// ClosedPullRequest names the superseded original candidate's own pull
	// request when this rebatch closed it (red-team finding M6): a
	// published-unlanded original has very likely already armed GitHub
	// auto-merge (the PR-land engine arms it before any check wait), and
	// leaving it open would let GitHub land the superseded content
	// alongside this replacement the moment its checks — or a later
	// update-branch — go green. Empty when the original never published a
	// pull request, so there was nothing to close.
	ClosedPullRequest string `json:"closed_pull_request,omitempty"`
}

type WorktreeMergePublishedCandidateAdoption struct {
	SchemaVersion       int                    `json:"schema_version"`
	ID                  string                 `json:"id"`
	Status              string                 `json:"status"`
	ReceiptPath         string                 `json:"receipt_path"`
	AcknowledgementPath string                 `json:"acknowledgement_path"`
	ReceiptSHA256       string                 `json:"receipt_sha256"`
	ReceiptID           string                 `json:"receipt_id"`
	Lane                string                 `json:"lane"`
	Repository          string                 `json:"repository"`
	Target              string                 `json:"target"`
	Candidate           WorktreeMergeCandidate `json:"candidate"`
	PullRequest         string                 `json:"pull_request"`
	Actor               string                 `json:"actor"`
	Reason              string                 `json:"reason"`
	RecordedAt          time.Time              `json:"recorded_at"`
}

type WorktreeMergePublishedCandidateAdoptionOptions struct {
	ProjectsRoot, Receipt, PullRequest string
	Apply                              bool
	Actor, Reason                      string
}

type WorktreeMergePublishedForwardRepair struct {
	Status               string                                   `json:"status"`
	ReceiptPath          string                                   `json:"receipt_path"`
	ReceiptSHA256        string                                   `json:"receipt_sha256"`
	ImmutableClaimSHA256 string                                   `json:"immutable_claim_sha256"`
	SupersessionPath     string                                   `json:"supersession_path"`
	SupersessionSHA256   string                                   `json:"supersession_sha256"`
	CurrentTargetSHA     string                                   `json:"current_target_sha"`
	Sources              []WorktreeMergeSource                    `json:"sources"`
	RequiredRoots        []WorktreeMergeValidationFailureSealRoot `json:"required_roots"`
	Candidate            WorktreeMergeCandidate                   `json:"candidate"`
	Actor                string                                   `json:"actor"`
	Reason               string                                   `json:"reason"`
}

type WorktreeMergePublishedForwardRepairOptions struct {
	ProjectsRoot, Receipt, ExpectedReceiptSHA256, ExpectedImmutableClaimSHA256 string
	ExpectedSupersessionSHA256, ExpectedCurrentTargetSHA                       string
	Sources, ExpectedSourceSHAs                                                []string
	Apply                                                                      bool
	Actor, Reason                                                              string
	Model, AgentRuntime, AgentID, Initiator, CLI, Provider                     string
	SessionRequired                                                            bool
	Timeout                                                                    time.Duration
	Retry                                                                      int
}

type WorktreeMergePushGateReceipt struct {
	Remote            string    `json:"remote"`
	RemoteRef         string    `json:"remote_ref"`
	PreviousRemoteSHA string    `json:"previous_remote_sha"`
	LocalSHA          string    `json:"local_sha"`
	Status            string    `json:"status"`
	ObservedAt        time.Time `json:"observed_at"`
}

type WorktreeMergeRebaseReceipt struct {
	CandidateBefore string `json:"candidate_before"`
	TargetBefore    string `json:"target_before"`
	TargetAfter     string `json:"target_after"`
	CandidateAfter  string `json:"candidate_after"`
}

type WorktreeMergeReceipt struct {
	SchemaVersion         int                         `json:"schema_version"`
	ID                    string                      `json:"id"`
	Lane                  string                      `json:"lane"`
	Phase                 WorktreeMergePhase          `json:"phase"`
	Status                WorktreeMergeStatus         `json:"status"`
	Repository            string                      `json:"repository"`
	Target                string                      `json:"target"`
	TargetSHA             string                      `json:"target_sha"`
	Sources               []WorktreeMergeSource       `json:"sources"`
	Candidate             WorktreeMergeCandidate      `json:"candidate"`
	Rebase                *WorktreeMergeRebaseReceipt `json:"rebase,omitempty"`
	RevertOf              *WorktreeMergeRevertReceipt `json:"revert_of,omitempty"`
	Route                 WorktreeMergeRouteDecision  `json:"route,omitempty"`
	PullRequest           string                      `json:"pull_request,omitempty"`
	PublishedCandidateSHA string                      `json:"published_candidate_sha,omitempty"`
	PreviousTargetSHA     string                      `json:"previous_target_sha,omitempty"`
	LandingSHA            string                      `json:"landing_sha,omitempty"`
	CanonicalSync         string                      `json:"canonical_sync,omitempty"`
	LocalSync             string                      `json:"local_sync,omitempty"`
	Validation            quality.VerificationReport  `json:"validation,omitempty"`
	BaselineValidation    quality.VerificationReport  `json:"baseline_validation,omitempty"`
	// ValidationDeferral is set exactly when local validation was skipped for
	// the pull-request route rather than run. See
	// WorktreeMergeValidationDeferral.
	ValidationDeferral *WorktreeMergeValidationDeferral `json:"validation_deferral,omitempty"`
	ValidationIdentity *WorktreeMergeValidationIdentity `json:"validation_identity,omitempty"`
	ValidationTimeouts *WorktreeMergeValidationTimeouts `json:"validation_timeouts,omitempty"`
	// Findings are non-blocking observations recorded alongside an otherwise
	// successful outcome (sneat-dev/wb#591 round 3 red-team follow-up): they
	// never cause a refusal and never lengthen a wait. See
	// WorktreeMergeFinding and recordDeferredValidationCheckSkippedFinding.
	Findings       []WorktreeMergeFinding              `json:"findings,omitempty"`
	Checks         PullRequestWaitResult               `json:"checks,omitempty"`
	PushGate       *WorktreeMergePushGateReceipt       `json:"push_gate,omitempty"`
	ForwardRepairs []WorktreeMergeForwardRepairReceipt `json:"forward_repairs,omitempty"`
	Cleanup        bool                                `json:"cleanup_requested"`
	// AllowUnfenced is monotonic landing intent: an interrupted resume keeps
	// the explicit approval to rely on observed exact-head checks when the
	// target has no server-enforced strict up-to-date fence.
	AllowUnfenced      bool                                           `json:"allow_unfenced,omitempty"`
	OnFailure          string                                         `json:"on_failure,omitempty"`
	CleanupReports     []string                                       `json:"cleanup_reports,omitempty"`
	CleanedTasks       []string                                       `json:"cleaned_tasks,omitempty"`
	SourceRefreshes    []WorktreeMergeSourceRefresh                   `json:"source_refreshes,omitempty"`
	TargetRefreshes    []WorktreeMergeTargetRefresh                   `json:"target_refreshes,omitempty"`
	SourcePullRequests []WorktreeMergeSourcePullRequestReconciliation `json:"source_pull_requests,omitempty"`
	// AutoMergeArmed records that the PR route armed GitHub auto-merge for
	// this receipt's pull request. It says nothing about who performed the
	// merge: MergedBy records that when GitHub did.
	AutoMergeArmed bool `json:"auto_merge_armed,omitempty"`
	// MergedBy names who performed the merge when it was not this WB
	// invocation's own merge write — "github auto-merge" when armed
	// auto-merge landed it while WB was waiting, resuming, or absent.
	MergedBy string `json:"merged_by,omitempty"`
	// SupersededPullRequest names a prior candidate's own pull request that
	// a rebatch replacing it closed (red-team finding M6), so its armed
	// auto-merge could not land it alongside this replacement. Empty when
	// this candidate is not a rebatch replacement of a published-unlanded
	// original.
	SupersededPullRequest string `json:"superseded_pull_request,omitempty"`
	// RebatchOf binds this candidate to an immutable prepared receipt whose
	// source set was safely expanded. The old receipt is never rewritten.
	RebatchOf           string                   `json:"rebatch_of,omitempty"`
	RebatchedCandidates []WorktreeMergeCandidate `json:"rebatched_candidates,omitempty"`
	Failure             string                   `json:"failure,omitempty"`
	ResumeArgs          []string                 `json:"resume_args,omitempty"`
	// HostLoadAdmission records the most recent host-load admission check
	// that actually ran for this receipt's lane, so the override is provable
	// from the receipt rather than only from the caller's own log. Set by
	// cmd/wb before the orchestrate call whose validation the check gates.
	HostLoadAdmission *WorktreeMergeHostLoadAdmission `json:"host_load_admission,omitempty"`
	// LaneOwner is the landing-lane record this receipt's session acquired,
	// when the caller populated Lane (see LaneGuardRequest); nil when no
	// guard ran. Recording it on the receipt is what lets `--format json`
	// show a takeover's reason and prior owner, matching what `cmd/wb`'s help
	// and ai/skills/wb-merge/SKILL.md promise.
	LaneOwner   *landinglane.Record `json:"lane_owner,omitempty"`
	ReceiptPath string              `json:"receipt_path"`
	CreatedAt   time.Time           `json:"created_at"`
	UpdatedAt   time.Time           `json:"updated_at"`
}

type WorktreeMergeReceiptCollisionAcknowledgement struct {
	SchemaVersion                               int                    `json:"schema_version"`
	ID                                          string                 `json:"id"`
	Status                                      string                 `json:"status"`
	ReceiptPath                                 string                 `json:"receipt_path"`
	AcknowledgementPath                         string                 `json:"acknowledgement_path"`
	ReceiptSHA256                               string                 `json:"receipt_sha256"`
	ImmutableClaimSHA256                        string                 `json:"immutable_claim_sha256"`
	ReceiptID                                   string                 `json:"receipt_id"`
	Lane                                        string                 `json:"lane"`
	Repository                                  string                 `json:"repository"`
	Target                                      string                 `json:"target"`
	ExpectedTargetSHA                           string                 `json:"expected_target_sha"`
	ExpectedCandidateSHA                        string                 `json:"expected_candidate_sha"`
	ExpectedCurrentSourceSHA                    string                 `json:"expected_current_source_sha"`
	ExpectedHistoricalRefreshSourceSHA          string                 `json:"expected_historical_refresh_source_sha"`
	ClaimBaseSHA                                string                 `json:"claim_base_sha"`
	Candidate                                   WorktreeMergeCandidate `json:"candidate"`
	CurrentSources                              []WorktreeMergeSource  `json:"current_sources"`
	HistoricalRefreshSources                    []WorktreeMergeSource  `json:"historical_refresh_sources"`
	HistoricalValidationFailedOperatorAssertion bool                   `json:"historical_validation_failed_operator_assertion"`
	Actor                                       string                 `json:"actor"`
	Reason                                      string                 `json:"reason"`
	RecordedAt                                  time.Time              `json:"recorded_at"`
}

type WorktreeMergeReceiptCollisionAcknowledgementOptions struct {
	ProjectsRoot, Receipt, ExpectedReceiptSHA256, ExpectedImmutableClaimSHA256                            string
	ExpectedTargetSHA, ExpectedCandidateSHA, ExpectedCurrentSourceSHA, ExpectedHistoricalRefreshSourceSHA string
	Apply                                                                                                 bool
	Actor, Reason                                                                                         string
}

type WorktreeMergeRetiredPrepareCandidateAcknowledgementOptions struct {
	ProjectsRoot, Receipt, Actor, Reason string
	Apply                                bool
}

type WorktreeMergeRetiredPublicationAcknowledgement struct {
	SchemaVersion         int                   `json:"schema_version"`
	ID                    string                `json:"id"`
	Status                string                `json:"status"`
	ReceiptPath           string                `json:"receipt_path"`
	AcknowledgementPath   string                `json:"acknowledgement_path"`
	ReceiptID             string                `json:"receipt_id"`
	ReceiptSHA256         string                `json:"receipt_sha256"`
	ReceiptPhase          WorktreeMergePhase    `json:"receipt_phase"`
	ReceiptStatus         WorktreeMergeStatus   `json:"receipt_status"`
	Lane                  string                `json:"lane"`
	Repository            string                `json:"repository"`
	Target                string                `json:"target"`
	ReceiptTargetSHA      string                `json:"receipt_target_sha"`
	CurrentTargetSHA      string                `json:"current_target_sha"`
	CandidateTask         string                `json:"candidate_task"`
	CandidateWorktree     string                `json:"candidate_worktree"`
	CandidateBranch       string                `json:"candidate_branch"`
	CandidateSHA          string                `json:"candidate_sha,omitempty"`
	PublishedCandidateSHA string                `json:"published_candidate_sha,omitempty"`
	PullRequest           string                `json:"pull_request"`
	PullRequestState      string                `json:"pull_request_state"`
	PullRequestClosedAt   string                `json:"pull_request_closed_at,omitempty"`
	PullRequestHeadSHA    string                `json:"pull_request_head_sha"`
	Sources               []WorktreeMergeSource `json:"sources"`
	Actor                 string                `json:"actor"`
	Reason                string                `json:"reason"`
	RecordedAt            time.Time             `json:"recorded_at"`
}

type WorktreeMergeRetiredPublicationAcknowledgementOptions struct {
	ProjectsRoot string
	Receipt      string
	Apply        bool
	Actor        string
	Reason       string
}

type WorktreeMergeRevertReceipt struct {
	PreviousTargetSHA string `json:"previous_target_sha"`
	LandingSHA        string `json:"landing_sha"`
	CandidateSHA      string `json:"candidate_sha"`
}

type WorktreeMergeRoute string

type WorktreeMergeRouteDecision struct {
	Requested WorktreeMergeRoute `json:"requested"`
	Route     WorktreeMergeRoute `json:"route"`
	Reason    string             `json:"reason"`
}

type WorktreeMergeSelfSupersessionCorrection struct {
	SchemaVersion           int                    `json:"schema_version"`
	ID                      string                 `json:"id"`
	Status                  string                 `json:"status"`
	CorrectionPath          string                 `json:"correction_path"`
	ReceiptPath             string                 `json:"receipt_path"`
	ReceiptSHA256           string                 `json:"receipt_sha256"`
	ImmutableClaimSHA256    string                 `json:"immutable_claim_sha256"`
	SupersessionPath        string                 `json:"supersession_path"`
	SupersessionSHA256      string                 `json:"supersession_sha256"`
	SupersessionID          string                 `json:"supersession_id"`
	OriginalCandidate       WorktreeMergeCandidate `json:"original_candidate"`
	OriginalClaimBaseSHA    string                 `json:"original_claim_base_sha"`
	CorrectedReplacement    WorktreeMergeCandidate `json:"corrected_replacement"`
	ReplacementClaimBaseSHA string                 `json:"replacement_claim_base_sha"`
	CurrentTargetSHA        string                 `json:"current_target_sha"`
	Sources                 []WorktreeMergeSource  `json:"sources"`
	Actor                   string                 `json:"actor"`
	Reason                  string                 `json:"reason"`
	RecordedAt              time.Time              `json:"recorded_at"`
}

type WorktreeMergeSelfSupersessionCorrectionOptions struct {
	ProjectsRoot, Receipt, ReplacementWorktree, ExpectedSupersessionSHA256, ExpectedImmutableClaimSHA256 string
	Apply                                                                                                bool
	Actor, Reason                                                                                        string
}

type WorktreeMergeSource struct {
	Task     string `json:"task"`
	Worktree string `json:"worktree"`
	Branch   string `json:"branch"`
	SHA      string `json:"sha"`
	Merged   bool   `json:"merged"`
}

type WorktreeMergeSourcePullRequestReconciliation struct {
	Number       int       `json:"number"`
	URL          string    `json:"url"`
	SourceSHA    string    `json:"source_sha"`
	ObservedSHA  string    `json:"observed_sha,omitempty"`
	ObservedBase string    `json:"observed_base,omitempty"`
	Outcome      string    `json:"outcome"`
	Commented    bool      `json:"commented,omitempty"`
	Closed       bool      `json:"closed,omitempty"`
	Reason       string    `json:"reason,omitempty"`
	UpdatedAt    time.Time `json:"updated_at"`
}

type WorktreeMergeSourceRefresh struct {
	RecordedAt time.Time             `json:"recorded_at"`
	Sources    []WorktreeMergeSource `json:"sources"`
}

type WorktreeMergeStatus string

type WorktreeMergeStrandedLandingAcknowledgement struct {
	SchemaVersion       int                 `json:"schema_version"`
	ID                  string              `json:"id"`
	Status              string              `json:"status"`
	ReceiptPath         string              `json:"receipt_path"`
	AcknowledgementPath string              `json:"acknowledgement_path"`
	ReceiptID           string              `json:"receipt_id"`
	ReceiptSHA256       string              `json:"receipt_sha256"`
	ReceiptStatus       WorktreeMergeStatus `json:"receipt_status"`
	Lane                string              `json:"lane"`
	Repository          string              `json:"repository"`
	Target              string              `json:"target"`
	ReceiptTargetSHA    string              `json:"receipt_target_sha"`
	CandidateSHA        string              `json:"candidate_sha"`
	PullRequest         string              `json:"pull_request"`
	// PullRequestHeadSHA records a strict descendant of CandidateSHA that
	// GitHub reports as the merged pull request head. It is empty when the PR
	// head still exactly matches CandidateSHA. A descendant is accepted only
	// when GitHub proves both its ancestry and its containment in the current
	// remote target.
	PullRequestHeadSHA string `json:"pull_request_head_sha,omitempty"`
	// ProvedLandingSHA is GitHub's own server merge-result commit for
	// PullRequest, discovered live by this acknowledgement. The historical
	// receipt's own LandingSHA is deliberately left empty by this recovery
	// path: the tool itself never observed the landing at the time, and this
	// field records the later, separately audited proof instead.
	ProvedLandingSHA string `json:"proved_landing_sha"`
	CurrentTargetSHA string `json:"current_target_sha"`
	// CandidateLanding names which proof established that the receipted
	// candidate is contained in CurrentTargetSHA: "ancestor" for a plain
	// merge (direct git ancestry) or "tree-identical" for a squash merge (or
	// a single-commit rebase merge), where the candidate can never be an
	// ancestor because the merge rewrites it but the server merge commit's
	// tree matches the candidate's own tree exactly.
	CandidateLanding string `json:"candidate_landing"`
	// CandidateLandingTreeSHA is the tree SHA the two commits were proved to
	// share, set only when CandidateLanding is "tree-identical".
	CandidateLandingTreeSHA string                `json:"candidate_landing_tree_sha,omitempty"`
	Sources                 []WorktreeMergeSource `json:"sources"`
	Actor                   string                `json:"actor"`
	Reason                  string                `json:"reason"`
	RecordedAt              time.Time             `json:"recorded_at"`
}

type WorktreeMergeStrandedLandingAcknowledgementOptions struct {
	ProjectsRoot string
	Receipt      string
	Apply        bool
	Actor        string
	Reason       string
}

type WorktreeMergeTargetRefresh struct {
	RecordedAt           time.Time `json:"recorded_at"`
	PreviousTargetSHA    string    `json:"previous_target_sha"`
	NewTargetSHA         string    `json:"new_target_sha"`
	PreviousCandidateSHA string    `json:"previous_candidate_sha"`
	NewCandidateSHA      string    `json:"new_candidate_sha"`
}

type WorktreeMergeUnpublishedValidationFailureAcknowledgement struct {
	SchemaVersion           int                    `json:"schema_version"`
	ID                      string                 `json:"id"`
	Status                  string                 `json:"status"`
	ReceiptPath             string                 `json:"receipt_path"`
	AcknowledgementPath     string                 `json:"acknowledgement_path"`
	ReceiptID               string                 `json:"receipt_id"`
	ReceiptSHA256           string                 `json:"receipt_sha256"`
	Lane                    string                 `json:"lane"`
	Repository              string                 `json:"repository"`
	Target                  string                 `json:"target"`
	ReceiptTargetSHA        string                 `json:"receipt_target_sha"`
	CurrentTargetSHA        string                 `json:"current_target_sha"`
	Candidate               WorktreeMergeCandidate `json:"candidate"`
	CandidateCleanupBacklog string                 `json:"candidate_cleanup_backlog,omitempty"`
	Sources                 []WorktreeMergeSource  `json:"sources"`
	PreservedSources        []WorktreeMergeSource  `json:"preserved_sources,omitempty"`
	Actor                   string                 `json:"actor"`
	Reason                  string                 `json:"reason"`
	RecordedAt              time.Time              `json:"recorded_at"`
}

type WorktreeMergeUnpublishedValidationFailureAcknowledgementOptions struct {
	ProjectsRoot string
	Receipt      string
	Apply        bool
	Actor        string
	Reason       string
}

type WorktreeMergeValidationDeferral struct {
	Route        WorktreeMergeRoute `json:"route"`
	CandidateSHA string             `json:"candidate_sha"`
	Reason       string             `json:"reason"`
	RecordedAt   time.Time          `json:"recorded_at"`
}

type WorktreeMergeValidationFailureSeal struct {
	Status           string                                   `json:"status"`
	ReceiptPath      string                                   `json:"receipt_path"`
	ReceiptID        string                                   `json:"receipt_id"`
	ReceiptSHA256    string                                   `json:"receipt_sha256"`
	Repository       string                                   `json:"repository"`
	Target           string                                   `json:"target"`
	CurrentTargetSHA string                                   `json:"current_target_sha"`
	TargetTreeSHA    string                                   `json:"target_tree_sha"`
	RequiredRoots    []WorktreeMergeValidationFailureSealRoot `json:"required_roots"`
	Candidate        WorktreeMergeCandidate                   `json:"candidate"`
	Actor            string                                   `json:"actor"`
	Reason           string                                   `json:"reason"`
}

type WorktreeMergeValidationFailureSealOptions struct {
	ProjectsRoot    string
	Receipt         string
	Apply           bool
	Actor           string
	Reason          string
	Model           string
	AgentRuntime    string
	AgentID         string
	Initiator       string
	CLI             string
	Provider        string
	SessionRequired bool
	Timeout         time.Duration
	Retry           int
}

type WorktreeMergeValidationFailureSealRoot struct {
	Kind string `json:"kind"`
	SHA  string `json:"sha"`
}

type WorktreeMergeValidationFailureSupersession struct {
	SchemaVersion                  int                    `json:"schema_version"`
	ID                             string                 `json:"id"`
	Status                         string                 `json:"status"`
	ReceiptPath                    string                 `json:"receipt_path"`
	AcknowledgementPath            string                 `json:"acknowledgement_path"`
	ReceiptID                      string                 `json:"receipt_id"`
	ReceiptSHA256                  string                 `json:"receipt_sha256"`
	ReceiptStatus                  WorktreeMergeStatus    `json:"receipt_status"`
	Lane                           string                 `json:"lane"`
	Repository                     string                 `json:"repository"`
	Target                         string                 `json:"target"`
	ReceiptTargetSHA               string                 `json:"receipt_target_sha"`
	CurrentTargetSHA               string                 `json:"current_target_sha"`
	OriginalCandidate              WorktreeMergeCandidate `json:"original_candidate"`
	ObservedCandidateDescendantSHA string                 `json:"observed_candidate_descendant_sha,omitempty"`
	OriginalClaimBaseSHA           string                 `json:"original_claim_base_sha"`
	Replacement                    WorktreeMergeCandidate `json:"replacement"`
	ReplacementClaimBaseSHA        string                 `json:"replacement_claim_base_sha"`
	Sources                        []WorktreeMergeSource  `json:"sources"`
	Actor                          string                 `json:"actor"`
	Reason                         string                 `json:"reason"`
	RecordedAt                     time.Time              `json:"recorded_at"`
}

type WorktreeMergeValidationFailureSupersessionOptions struct {
	ProjectsRoot        string
	Receipt             string
	ReplacementWorktree string
	Apply               bool
	Actor               string
	Reason              string
}

type WorktreeMergeValidationIdentity struct {
	CandidateSHA     string            `json:"candidate_sha"`
	TargetSHA        string            `json:"target_sha"`
	SourceSHAs       []string          `json:"source_shas"`
	QualityPolicySHA string            `json:"quality_policy_sha"`
	WBBuild          string            `json:"wb_build"`
	WBExecutableSHA  string            `json:"wb_executable_sha"`
	Validators       map[string]string `json:"validators,omitempty"`
}

type WorktreeMergeValidationTimeouts struct {
	Check        time.Duration `json:"check_timeout,omitempty"`
	ShardAttempt time.Duration `json:"shard_attempt_timeout,omitempty"`
}