orchestrate

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

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"`
	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 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 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 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 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: a
	// review file path or a pull-request comment URL. The durable review ledger
	// is a later phase; until it exists this value is recorded verbatim on the
	// receipt so the approval is at least attributable.
	ApprovedBy 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
	// 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"`
	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"`

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

	BranchDeleted bool   `json:"branch_deleted"`
	LandingOnBase bool   `json:"landing_on_base"`
	CanonicalSync string `json:"canonical_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"`
}

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"`
}

type PullRequestWaitStatus string

type RemoteCheck struct {
	Name   string `json:"name" yaml:"name"`
	Bucket string `json:"bucket" yaml:"bucket"`
	Link   string `json:"link,omitempty" yaml:"link,omitempty"`
	AppID  int64  `json:"app_id,omitempty" yaml:"app_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 SourceCommit struct {
	SHA     string `json:"sha"`
	Subject string `json:"subject"`
	Body    string `json:"body,omitempty"`
}

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 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 WorktreeMergeLandOptions struct {
	ProjectsRoot      string
	Receipt           string
	Route             WorktreeMergeRoute
	Cleanup           bool
	OnFailure         string
	Timeout           time.Duration
	Retry             int
	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
}

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 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
	// 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 receipt whose
	// sources are being replaced additively and/or extended in this prepare.
	RebatchReceipt string
}

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"`
}

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"`
	Validation            quality.VerificationReport          `json:"validation,omitempty"`
	BaselineValidation    quality.VerificationReport          `json:"baseline_validation,omitempty"`
	ValidationIdentity    *WorktreeMergeValidationIdentity    `json:"validation_identity,omitempty"`
	ValidationTimeouts    *WorktreeMergeValidationTimeouts    `json:"validation_timeouts,omitempty"`
	Checks                PullRequestWaitResult               `json:"checks,omitempty"`
	PushGate              *WorktreeMergePushGateReceipt       `json:"push_gate,omitempty"`
	ForwardRepairs        []WorktreeMergeForwardRepairReceipt `json:"forward_repairs,omitempty"`
	Cleanup               bool                                `json:"cleanup_requested"`
	OnFailure             string                              `json:"on_failure,omitempty"`
	CleanupReports        []string                            `json:"cleanup_reports,omitempty"`
	CleanedTasks          []string                            `json:"cleaned_tasks,omitempty"`
	SourceRefreshes       []WorktreeMergeSourceRefresh        `json:"source_refreshes,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"`
	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 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 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"`
	// 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"`
	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 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"`
}