worktrees

type AbortDisposition string

type AbortOptions struct {
	ProjectsRoot string
	Task         string
	Base         string
	Disposition  AbortDisposition
	Successor    string
	// SuccessorIdentity is the caller's explicit execution identity declaration
	// for the claim created by an applied handoff/not_landed transition.
	SuccessorIdentity ClaimExecutionIdentity
	DeleteRemote      bool
	Apply             bool
	// contains filtered or unexported fields
}

type AbortResult struct {
	ListResult
	Disposition   AbortDisposition `json:"disposition"`
	Successor     string           `json:"successor,omitempty"`
	Eligible      bool             `json:"eligible"`
	Applied       bool             `json:"applied"`
	WorktreeGone  bool             `json:"worktree_gone"`
	BranchDeleted bool             `json:"branch_deleted"`
	RemoteDeleted bool             `json:"remote_deleted"`
	BacklogID     string           `json:"backlog_id,omitempty"`
	Reason        string           `json:"reason,omitempty"`
}

type Admission struct {
	Mode     AdmissionMode `json:"mode"`
	Admitted bool          `json:"admitted"`
	Reason   string        `json:"reason,omitempty"`
	Remedy   string        `json:"remedy,omitempty"`
}

type AdmissionMode string

type BackfillOptions struct {
	ProjectsRoot string
	Base         string
	Apply        bool
}

type BackfillResult struct {
	Path       string `json:"path"`
	Repository string `json:"repository"`
	EffortID   string `json:"effort_id,omitempty"`
	Layout     string `json:"layout"`
	Action     string `json:"action"`
	Reason     string `json:"reason,omitempty"`
}

type ClaimExecutionIdentity struct {
	Model    string
	CLI      string
	Provider string
}

type CleanupOptions struct {
	ProjectsRoot string
	Task         string
	Base         string
	// Filter narrows both which candidates are validated and which are acted
	// on to those whose owner/repository slug contains this substring — see
	// ListOptions.Filter. An empty Filter matches everything, preserving
	// today's behavior exactly.
	Filter string
	// AbsorbedBy is the optional landing receipt pointer described on
	// ListOptions.AbsorbedBy. It is verified, never trusted.
	AbsorbedBy   string
	AllMerged    bool
	Apply        bool
	DeleteRemote bool
	OlderThan    time.Duration
	ReportDir    string
	Now          func() time.Time
	// contains filtered or unexported fields
}

type CleanupOutcome struct {
	Results     []CleanupResult     `json:"results"`
	ReportPath  string              `json:"report_path,omitempty"`
	Diagnostics []ListDiagnostic    `json:"diagnostics,omitempty"`
	Artifacts   []LifecycleArtifact `json:"artifacts,omitempty"`
}

type CleanupResult struct {
	ListResult
	Eligible      bool   `json:"eligible"`
	Applied       bool   `json:"applied"`
	RemoteDeleted bool   `json:"remote_deleted"`
	WorktreeGone  bool   `json:"worktree_gone"`
	BranchDeleted bool   `json:"branch_deleted"`
	BacklogID     string `json:"backlog_id,omitempty"`
	Reason        string `json:"reason,omitempty"`
}

type CorrectExecutionIdentityOptions struct {
	ProjectsRoot string
	EffortID     string
	RunID        string
	ClaimID      string
	EventID      string
	Actor        string
	Reason       string
	Model        *string
	CLI          *string
	Provider     *string
}

type CreateOptions struct {
	ProjectsRoot string
	Operation    string
	// Branch is an exact branch name. It has highest precedence and is never
	// derived from agent or harness identity.
	Branch string
	// BranchChosen distinguishes an omitted branch from an explicitly empty
	// --branch flag, which is invalid rather than a request to fall back.
	BranchChosen bool
	// BranchPrefix derives <prefix><operation> when Branch is empty. The
	// companion boolean preserves the meaningful explicit empty CLI value,
	// which disables any persisted prefix for this invocation.
	BranchPrefix       string
	BranchPrefixChosen bool
	Base               string
	Resume             bool
	WorkLog            WorkLogOptions
	// contains filtered or unexported fields
}

type CreatePublicationError struct {
	Outcomes []CreateRecoveryOutcome `json:"outcomes"`
	Err      error                   `json:"-"`
}

type CreateRecoveryOutcome struct {
	Result             CreateResult              `json:"result"`
	HeadSHA            string                    `json:"head_sha"`
	WorkLog            WorkLogPublicationOutcome `json:"work_log"`
	CleanupBacklogID   string                    `json:"cleanup_backlog_id,omitempty"`
	CleanupBacklogPath string                    `json:"cleanup_backlog_path,omitempty"`
	BacklogPersisted   bool                      `json:"backlog_persisted"`
	RollbackCompleted  bool                      `json:"rollback_completed"`
	RecoveryError      string                    `json:"recovery_error,omitempty"`
}

type CreateResult struct {
	Repository       string `json:"repository"`
	CanonicalDir     string `json:"canonical_dir"`
	WorktreeDir      string `json:"worktree_dir"`
	Branch           string `json:"branch"`
	Base             string `json:"base"`
	BaseSHA          string `json:"base_sha"`
	Action           string `json:"action"`
	WorkLogPath      string `json:"work_log_path,omitempty"`
	CleanupBacklogID string `json:"cleanup_backlog_id,omitempty"`
}

type ExecutionIdentity struct {
	Model           string   `json:"model"`
	ModelProvenance string   `json:"model_provenance"`
	ModelDeclaredBy string   `json:"model_declared_by,omitempty"`
	CLI             string   `json:"cli,omitempty"`
	Provider        string   `json:"provider,omitempty"`
	CorrectionIDs   []string `json:"correction_ids,omitempty"`
}

type ExecutionIdentityCorrectionResult struct {
	ClaimID      string            `json:"claim_id"`
	CorrectionID string            `json:"correction_id"`
	Identity     ExecutionIdentity `json:"identity"`
	OutboxPath   string            `json:"outbox_path"`
}

type GuardOptions struct {
	ProjectsRoot string
	Base         string

	// Admission gates a commit on the worktree carrying its own record. It is
	// off unless a caller opts in, so guard's existing layout checks keep their
	// current meaning everywhere else.
	Admission AdmissionMode
}

type GuardResult struct {
	Path          string     `json:"path"`
	CanonicalDir  string     `json:"canonical_dir"`
	WorktreesRoot string     `json:"worktrees_root"`
	Branch        string     `json:"branch"`
	Kind          string     `json:"kind"`
	Transient     bool       `json:"transient,omitempty"`
	Admission     *Admission `json:"admission,omitempty"`
}

type LifecycleArtifact struct {
	Task          string `json:"task"`
	WorktreesRoot string `json:"worktrees_root"`
	Path          string `json:"path"`
	Kind          string `json:"kind"`
	State         string `json:"state"`
	Disposition   string `json:"disposition"`
	Eligible      bool   `json:"eligible"`
	Applied       bool   `json:"applied"`
	ArchivePath   string `json:"archive_path,omitempty"`
	Reason        string `json:"reason,omitempty"`
}

type ListDiagnostic struct {
	Task          string `json:"task,omitempty"`
	WorktreesRoot string `json:"worktrees_root,omitempty"`
	Path          string `json:"path"`
	Message       string `json:"message"`
}

type ListOptions struct {
	ProjectsRoot string
	Task         string
	Base         string
	// Filter narrows the inventory to candidates whose owner/repository slug
	// (or, for a candidate that cannot be identified that cleanly, whatever
	// raw path-derived identity is available) contains this substring — the
	// same "only repos whose org/name contains this substring" semantics as
	// the root --filter flag elsewhere in WB. An empty Filter matches
	// everything, exactly like today. Filtering happens before a candidate's
	// diagnostic or result is retained, so a candidate outside the selection
	// can neither appear in the report nor influence it.
	Filter string
	GitHub bool
	// AbsorbedBy points at the merged pull request or exact landing commit
	// that carried a candidate's work into the target inside a differently
	// named integration branch. It selects which receipt to verify and never
	// substitutes for one: every containment proof still runs, so a wrong or
	// dishonest pointer can only fail closed. See absorbedLandingReceipt.
	AbsorbedBy string
}

type ListOutcome struct {
	SchemaVersion int                 `json:"schema_version"`
	Results       []ListResult        `json:"results"`
	Diagnostics   []ListDiagnostic    `json:"diagnostics,omitempty"`
	Artifacts     []LifecycleArtifact `json:"artifacts,omitempty"`
}

type ListResult struct {
	Task                 string `json:"task"`
	Repository           string `json:"repository"`
	CanonicalDir         string `json:"canonical_dir"`
	WorktreeDir          string `json:"worktree_dir"`
	WorktreesRoot        string `json:"worktrees_root"`
	Branch               string `json:"branch"`
	Base                 string `json:"base"`
	HeadSHA              string `json:"head_sha"`
	RemoteHeadSHA        string `json:"remote_head_sha,omitempty"`
	RemoteTargetSHA      string `json:"remote_target_sha,omitempty"`
	IntegratedAtOrigin   bool   `json:"integrated_at_origin"`
	RebaseMergedAtOrigin bool   `json:"rebase_merged_at_origin,omitempty"`
	AbsorbedAtOrigin     bool   `json:"absorbed_at_origin,omitempty"`
	AbsorbedBySHA        string `json:"absorbed_by_sha,omitempty"`
	// AbsorbedByRejection explains why an explicitly supplied --absorbed-by
	// receipt did not hold. An operator pointer that fails verification is a
	// precise, reportable refusal of that candidate, never a malformed
	// worktree and never a reason to abort a fleet-wide sweep.
	AbsorbedByRejection string       `json:"absorbed_by_rejection,omitempty"`
	Clean               bool         `json:"clean"`
	LocallyMerged       bool         `json:"locally_merged"`
	Locked              bool         `json:"locked"`
	LastCommit          time.Time    `json:"last_commit"`
	OpenPullRequest     *PullRequest `json:"open_pull_request,omitempty"`
	MergedPullRequest   *PullRequest `json:"merged_pull_request,omitempty"`
}

type Manifest struct {
	Version      int       `yaml:"version"`
	EffortID     string    `yaml:"effort_id"`
	ParentEffort string    `yaml:"parent_effort,omitempty"`
	EffortKind   string    `yaml:"effort_kind"`
	Repository   string    `yaml:"repository"`
	Worktree     string    `yaml:"worktree"`
	Branch       string    `yaml:"branch"`
	Base         string    `yaml:"base"`
	BaseSHA      string    `yaml:"base_sha"`
	CreatedAt    time.Time `yaml:"created_at"`
	Initiator    string    `yaml:"initiator,omitempty"`
	AgentID      string    `yaml:"agent_id,omitempty"`
	AgentRuntime string    `yaml:"agent_runtime,omitempty"`
	Model        string    `yaml:"model,omitempty"`
	CLI          string    `yaml:"cli,omitempty"`
	Provider     string    `yaml:"provider,omitempty"`
	RunID        string    `yaml:"run_id,omitempty"`
	ClaimID      string    `yaml:"claim_id,omitempty"`
	Provenance   string    `yaml:"provenance"`

	// InferredFields and Evidence are populated only for a reconstructed
	// manifest, so a reader can see exactly which values were guessed and from
	// what. They stay empty for provenance: created.
	InferredFields []string `yaml:"inferred_fields,omitempty"`
	Evidence       []string `yaml:"evidence,omitempty"`
}

type OrphanFamily struct {
	RootEffort  string           `json:"root_effort"`
	Worktrees   []OrphanWorktree `json:"worktrees"`
	Disposition string           `json:"disposition"`
	Reason      string           `json:"reason,omitempty"`
}

type OrphanOptions struct {
	ProjectsRoot string
	Base         string
	// StaleAfter is how long without a commit before an unmerged worktree needs
	// a decision. It never makes anything eligible for automatic removal.
	StaleAfter time.Duration
	// Now is injectable so ages are deterministic under test.
	Now time.Time
}

type OrphanReport struct {
	Families  []OrphanFamily `json:"families"`
	Totals    OrphanTotals   `json:"totals"`
	Unscanned []string       `json:"unscanned,omitempty"`
}

type OrphanTotals struct {
	Worktrees   int            `json:"worktrees"`
	Families    int            `json:"families"`
	ByLayout    map[string]int `json:"by_layout"`
	ByDispositn map[string]int `json:"by_disposition"`
	NoManifest  int            `json:"without_manifest"`
	Dirty       int            `json:"dirty"`
}

type OrphanWorktree struct {
	Path         string `json:"path"`
	CanonicalDir string `json:"canonical_dir"`
	Repository   string `json:"repository"`
	Layout       string `json:"layout"`
	Branch       string `json:"branch"`
	EffortID     string `json:"effort_id"`
	ParentEffort string `json:"parent_effort,omitempty"`
	RootEffort   string `json:"root_effort"`

	HasManifest bool   `json:"has_manifest"`
	Provenance  string `json:"provenance,omitempty"`
	HasPrompts  bool   `json:"has_prompts"`
	PromptCount int    `json:"prompt_count"`

	LastCommit time.Time `json:"last_commit,omitempty"`
	AgeDays    int       `json:"age_days"`
	Dirty      bool      `json:"dirty"`
	Missing    bool      `json:"missing"`
	Merged     bool      `json:"merged_into_target"`

	Disposition string   `json:"disposition"`
	Evidence    []string `json:"evidence"`
}

type PromptHeader struct {
	Seq      int       `yaml:"seq"`
	At       time.Time `yaml:"at"`
	SHA256   string    `yaml:"sha256"`
	Source   string    `yaml:"source"`
	Runtime  string    `yaml:"runtime,omitempty"`
	Model    string    `yaml:"model,omitempty"`
	CLI      string    `yaml:"cli,omitempty"`
	Provider string    `yaml:"provider,omitempty"`
	Slug     string    `yaml:"-"`
}

type PullRequest struct {
	Number   int        `json:"number"`
	URL      string     `json:"url"`
	State    string     `json:"state"`
	Base     string     `json:"base"`
	HeadSHA  string     `json:"head_sha"`
	MergeSHA string     `json:"merge_sha,omitempty"`
	Merged   *time.Time `json:"merged_at,omitempty"`
}

type RenameOptions struct {
	ProjectsRoot string
	OldTask      string
	NewTask      string
	// Filter narrows which of OldTask's repositories are renamed to those
	// whose owner/repository slug contains this substring — see
	// ListOptions.Filter for the exact semantics. An empty Filter renames
	// every repository under OldTask.
	Filter string
	// Branch is an exact feature branch. When empty, WB derives a branch from
	// BranchPrefix or layered worktrees policy; without a prefix the new task
	// slug itself is the branch name.
	Branch             string
	BranchChosen       bool
	BranchPrefix       string
	BranchPrefixChosen bool
	Base               string
	// DeleteOldBranch is retained for source compatibility; recycle always
	// deletes the old local branch. Force is the explicit discarded-work
	// authorization for an old branch not integrated into origin/Base.
	DeleteOldBranch bool
	// DeleteRemote must be explicit for apply. If origin/<old-branch> exists,
	// it must still equal the preflight head and is retired with an exact
	// force-with-lease after the old Work Log is durable.
	DeleteRemote bool
	Force        bool
	// PreserveCachePaths is the allow-list of ignored/untracked paths that may
	// survive recycle. Empty means no cache survives. Paths are repository
	// relative, safe, and audited in the rename report.
	PreserveCachePaths []string
	WorkLog            WorkLogOptions
	// Apply performs the rename. The default is a dry-run plan, exactly like
	// `wb worktree cleanup`.
	Apply     bool
	ReportDir string
	Now       func() time.Time
	// contains filtered or unexported fields
}

type RenameOutcome struct {
	Results     []RenameResult   `json:"results"`
	ReportPath  string           `json:"report_path,omitempty"`
	Diagnostics []ListDiagnostic `json:"diagnostics,omitempty"`
}

type RenameResult struct {
	OldTask             string   `json:"old_task"`
	NewTask             string   `json:"new_task"`
	Repository          string   `json:"repository"`
	CanonicalDir        string   `json:"canonical_dir"`
	OldWorktreeDir      string   `json:"old_worktree_dir"`
	NewWorktreeDir      string   `json:"new_worktree_dir"`
	OldBranch           string   `json:"old_branch"`
	NewBranch           string   `json:"new_branch"`
	Base                string   `json:"base"`
	Eligible            bool     `json:"eligible"`
	Applied             bool     `json:"applied"`
	Repaired            bool     `json:"repaired,omitempty"`
	OldBranchDeleted    bool     `json:"old_branch_deleted"`
	OldRemoteDeleted    bool     `json:"old_remote_deleted"`
	PreservedCachePaths []string `json:"preserved_cache_paths,omitempty"`
	Reason              string   `json:"reason,omitempty"`
}

type RepositoryRenameMismatchError struct {
	Worktree            string
	Owner               string
	PathRepository      string
	CanonicalRepository string
}

type WorkLogOptions struct {
	EffortID              string
	RunID                 string
	Initiator             string
	AgentID               string
	AgentRuntime          string
	Model                 string
	CLI                   string
	Provider              string
	OriginalPrompt        string // readable local file, copied to the private archive
	RequireOriginalPrompt bool   // public create/recycle commands require exact local recovery input
	// contains filtered or unexported fields
}

type WorkLogPublicationOutcome struct {
	ClaimPath         string `json:"claim_path,omitempty"`
	EffortID          string `json:"effort_id,omitempty"`
	RunID             string `json:"run_id,omitempty"`
	ClaimID           string `json:"claim_id,omitempty"`
	ClaimWritten      bool   `json:"claim_written"`
	ProjectionWritten bool   `json:"projection_written"`
	OutboxWritten     bool   `json:"outbox_written"`
	// contains filtered or unexported fields
}