worktrees

type AbortDisposition string

type AbortOptions struct {
	ProjectsRoot string
	Task         string
	Base         string
	// Filter narrows which repositories within the coordinated task are
	// inspected further than today's cheap local Git state, preflighted, and
	// mutated — the same "owner/repository slug (or worktree path) contains
	// this substring" semantics as ListOptions.Filter and the root --filter
	// flag. An empty Filter matches everything, preserving today's
	// all-repositories, all-or-nothing behavior exactly. A repository Filter
	// excludes is reported via AbortResult.Excluded rather than dropped
	// silently, its own ineligibility (if any) never blocks the repositories
	// Filter did select, and it is left completely untouched: the task
	// remains non-terminal until a later abort call resolves it too.
	Filter string
	// All acknowledges that this invocation intentionally applies a terminal
	// disposition to every member of a coordinated task. Multi-repository
	// tasks otherwise require an explicit member filter.
	All         bool
	Disposition AbortDisposition
	Successor   string
	// ClaimID, Actor, and Reason form the explicit authority boundary for an
	// orphaned terminal record. Orphaned claims have no live checkout from
	// which task/repository identity can be reconstructed, so apply always
	// binds one exact immutable claim rather than guessing from a task name.
	ClaimID string
	Actor   string
	Reason  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"`
	// Excluded marks a repository that AbortOptions.Filter left out of this
	// run. It is never preflighted or mutated regardless of Eligible, and
	// recording it here — rather than omitting it — is what lets a filtered
	// abort report precisely which repositories still remain unresolved.
	Excluded      bool                   `json:"excluded,omitempty"`
	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"`
	DirtyCapture  *DirtyWorktreeEvidence `json:"dirty_capture,omitempty"`
	Reason        string                 `json:"reason,omitempty"`
	// Quarantined names durable cleanup records this run declined to act on.
	// It is carried on the first result rather than aborting the run: the
	// backlog directory is shared, and somebody else's unreadable record must
	// not be able to refuse this task's abort.
	Quarantined []LifecycleBacklogQuarantine `json:"quarantined,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 AdoptOptions struct {
	ProjectsRoot string
	Base         string
	// Path adopts exactly this one worktree. Mutually exclusive with
	// AllExternal.
	Path string
	// AllExternal sweeps every worktree Orphans classifies as external.
	AllExternal bool
	// Filter narrows the sweep to candidates whose repository slug or path
	// contains this substring — the same contract as ListOptions.Filter and
	// the root --filter flag.
	Filter string
	Apply  bool
	// Initiator is the explicit human/operator identity for manual apply.
	Initiator string
	// Now is injectable so the recorded adoption time is deterministic under
	// test.
	Now func() time.Time
}

type AdoptResult struct {
	Path       string `json:"path"`
	Repository string `json:"repository,omitempty"`
	Task       string `json:"task,omitempty"`
	Branch     string `json:"branch,omitempty"`
	Base       string `json:"base,omitempty"`
	Action     string `json:"action"`
	Reason     string `json:"reason,omitempty"`
}

type AgentIdentity struct {
	Runtime string
	AgentID string
	Model   string
	PID     int
	// WBSessionID links a new Work Log claim to the registered session that
	// created it. A PID is only a liveness coordinate, never the identity.
	WBSessionID string
	// Registered distinguishes a resolver-backed identity from ambient
	// WB_AGENT_* declarations. Environment declarations are provenance, not
	// proof that a live session registered.
	Registered bool
}

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 BranchCleanupOptions struct {
	ProjectsRoot string
	Base         string
	Scope        string
	Apply        bool
	OlderThan    time.Duration
	ReportDir    string
	Filter       string
	Progress     io.Writer
	// Receipts enables landing-receipt classification, making receipted
	// branches eligible alongside contained ones. Off by default because it
	// costs a GitHub query per non-contained candidate. See
	// #req:receipted-is-opt-in-and-fails-closed.
	Receipts bool
	// AbsorbedBy is the optional operator-supplied landing pointer (a merged
	// pull request number or an exact landing commit) verified with the same
	// attested-absorption proof `wb worktree cleanup --absorbed-by` performs.
	// A branch that proves out is recorded as receipted, with the landing
	// commit carried in the plan exactly like a discovered receipt, so a
	// content-proven squash-absorbed branch whose worktree is already gone
	// can still be retired with an audited receipt. See
	// #req:attested-absorption-requires-exact-entry-point. Empty by default:
	// it never runs unless explicitly passed, and a pointer that fails to
	// verify for a given candidate refuses only that candidate.
	AbsorbedBy string
	// Now is injectable so age eligibility is deterministic under test.
	Now func() time.Time
}

type BranchCleanupOutcome struct {
	Base        string                `json:"base"`
	Scope       string                `json:"scope"`
	Apply       bool                  `json:"apply"`
	Results     []BranchCleanupResult `json:"results"`
	Diagnostics []string              `json:"diagnostics,omitempty"`
	Totals      map[string]int        `json:"totals"`
	ReportPath  string                `json:"report_path,omitempty"`
	ElapsedMS   int64                 `json:"elapsed_ms"`
}

type BranchCleanupResult struct {
	BranchEntry
	Eligible   bool   `json:"eligible"`
	SkipReason string `json:"skip_reason,omitempty"`
	Applied    bool   `json:"applied"`
	Outcome    string `json:"outcome"` // planned, deleted, skipped, or failed
	Error      string `json:"error,omitempty"`
}

type BranchEntry struct {
	Repository      string       `json:"repository"`
	Branch          string       `json:"branch"`
	Scope           string       `json:"scope"` // local or remote
	SHA             string       `json:"sha"`
	ShortSHA        string       `json:"short_sha"`
	CommitterDate   time.Time    `json:"committer_date,omitempty"`
	Base            string       `json:"base"`
	TargetSHA       string       `json:"target_sha,omitempty"`
	Disposition     string       `json:"disposition"`
	Evidence        string       `json:"evidence"`
	Reason          string       `json:"reason,omitempty"`
	Task            string       `json:"task,omitempty"`
	OpenPullRequest *PullRequest `json:"open_pull_request,omitempty"`
	// LandingSHA and ReceiptPullRequest carry a receipted branch's proved
	// landing so apply can re-verify the receipt — not ancestry, which a
	// receipted branch fails by construction — against the freshly fetched
	// target. See #req:receipted-requires-a-proved-landing.
	LandingSHA         string       `json:"landing_sha,omitempty"`
	ReceiptPullRequest *PullRequest `json:"receipt_pull_request,omitempty"`
	// PullRequestQueryFailed distinguishes "no open pull request" from "WB
	// could not ask GitHub." Cleanup's remote apply fails the whole scope
	// closed on the latter; list surfaces it but never refuses on it.
	PullRequestQueryFailed bool `json:"pull_request_query_failed,omitempty"`
	// AbsorbedByRejection explains why an operator-supplied --absorbed-by
	// pointer did not verify for this branch. It is set only when
	// --absorbed-by was passed and its attested-absorption proof (see
	// attestedAbsorbedReceipt, shared with `wb worktree cleanup
	// --absorbed-by`) failed for this candidate specifically; the branch keeps
	// whatever disposition its patch evidence (or --receipts) produces. A
	// wrong or dishonest pointer can therefore only fail closed, never widen
	// eligibility, and the rejection is reported rather than silently
	// swallowed.
	AbsorbedByRejection string `json:"absorbed_by_rejection,omitempty"`
}

type BranchListOptions struct {
	ProjectsRoot string
	Base         string
	Scope        string // local, remote, or all; default local
	Only         string // one disposition name; empty means every disposition
	OlderThan    time.Duration
	Filter       string
	// Progress receives incremental "[n/N] repository" lines as the sweep
	// works, plus a closing summary. Nil disables progress reporting.
	Progress io.Writer
}

type BranchListOutcome struct {
	Base        string         `json:"base"`
	Scope       string         `json:"scope"`
	Entries     []BranchEntry  `json:"entries"`
	Diagnostics []string       `json:"diagnostics,omitempty"`
	Totals      map[string]int `json:"totals"`
	ElapsedMS   int64          `json:"elapsed_ms"`
}

type CanonicalFreshness struct {
	Target      string    `json:"target"`
	RemoteRef   string    `json:"remote_ref"`
	LocalSHA    string    `json:"local_sha,omitempty"`
	RemoteSHA   string    `json:"remote_sha,omitempty"`
	Ahead       int       `json:"ahead,omitempty"`
	Behind      int       `json:"behind,omitempty"`
	Status      string    `json:"status"`
	Fetched     bool      `json:"fetched"`
	TargetDrift bool      `json:"target_drift,omitempty"`
	Error       string    `json:"error,omitempty"`
	ObservedAt  time.Time `json:"observed_at"`
}

type ClaimExecutionIdentity struct {
	Model    string
	CLI      string
	Provider string
}

type CleanupOptions struct {
	ProjectsRoot string
	Task         string
	// Tasks is an exact set of task names. Task remains for compatibility with
	// callers that select one task; callers must not set both.
	Tasks []string
	// Base is only the fallback for legacy candidates without a recorded
	// manifest/Work Log target. Recorded targets are resolved per candidate;
	// cleanup never applies one global base to a heterogeneous task.
	Base string
	// ExactRepository limits a named-task cleanup transaction to one exact
	// owner/repository slug. It is intended for repository-scoped orchestrators
	// such as worktree merge, where another repository may share the same task.
	// Filter remains the user-facing substring selector; this additional gate is
	// applied to the already inspected plan before any mutation.
	ExactRepository 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
	// SupersededBy is a path to an explicit trusted-reviewer supersession
	// receipt. It is only valid for a named cleanup task and is never inferred
	// from CI, PR state, or content similarity.
	SupersededBy string
	// MergeReceiptProofs are exact, orchestrator-produced cleanup proofs for
	// sources whose content was landed by an integration candidate and then
	// represented by a distinct commit with the same tree (for example, a
	// squash merge). They are deliberately unavailable to the user-facing
	// cleanup command: every proof is still rechecked against the source,
	// candidate, landing, and freshly fetched target before it can affect one
	// matching source worktree.
	MergeReceiptProofs []MergeReceiptCleanupProof
	// Progress is passed straight through to the inventory walk; see
	// ListOptions. A fleet-wide run is unobservable without it.
	Progress func(ListProgress)
	// Workers is the single concurrency ceiling for both phases: how many
	// candidates the inventory walk inspects at once (see ListOptions) and how
	// many tasks --all-merged applies at once. Apply concurrency is bounded by
	// the canonical repository rather than by this number — Git allows one
	// writer per clone — so raising it past the largest per-repository group
	// buys nothing. One makes both phases serial again.
	Workers   int
	AllMerged bool
	Apply     bool
	// ResumeInterrupted authorizes recovery of exactly the named task's
	// descriptor-validated interrupted lock before normal terminal cleanup.
	// It is deliberately unavailable to fleet cleanup.
	ResumeInterrupted bool
	DeleteRemote      bool
	// RequireRemoteRetirement asserts that this transaction must not finish a
	// named task while its source branch is still present on origin, because
	// the branch would survive as invisible backlog. It is an *evidence*
	// gate, not a flag-shape one: a candidate whose origin branch is already
	// gone has nothing left to retire and is cleaned without --remote. Only
	// the user-facing cleanup command sets it; orchestrators such as worktree
	// merge own their own remote-retirement sequencing.
	RequireRemoteRetirement bool
	OlderThan               time.Duration
	ReportDir               string
	Now                     func() time.Time
	// AllowResidue widens eligibility past exactly one refusal: a branch whose
	// work is provably landed by commit identity but which holds local commits
	// past the landed head. It is not a force flag — no proof is skipped, the
	// landing receipt must still hold — and the residual commits are printed
	// before they are discarded, because deleting the branch discards them.
	AllowResidue bool
	// IncludeDetached lets a detached checkout — the shape every pull-request
	// review creates — reach cleanup at all. It is only ever safe alongside
	// evidence that the checkout's head is a merged pull request's head, which
	// is what worktree gc classifies before it delegates here.
	IncludeDetached bool
	// TTL is reporting only, threaded to the inventory so a cleanup receipt can
	// state a candidate's age against the fleet's expiry window.
	TTL time.Duration
	// ResidueDepth bounds the commit-to-pull-request walk. See ListOptions.
	ResidueDepth int
	// Activity threads ListOptions.Activity, so a re-verification under the
	// task lock asks the same question the plan asked.
	Activity bool
	// 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"`
	// Purged records the terminal artefacts the inventory walk swept on its way
	// here. They are never part of the plan an operator approves: an empty
	// retired stage and an inert retired lock are WB's own debris, and their
	// removal is maintenance rather than a cleanup decision.
	Purged []PurgedArtefact `json:"purged,omitempty"`
	// Quarantined names the durable cleanup records this run declined to act
	// on. They are reported rather than swallowed, and they never abort the
	// run: the backlog directory is shared by every task on the machine, and
	// one record WB cannot validate must not refuse everybody else's cleanup.
	Quarantined []LifecycleBacklogQuarantine `json:"quarantined,omitempty"`
	Recovery    *InterruptedLockRecovery     `json:"recovery,omitempty"`
	// ResolvedTasks are the physical task namespaces Cleanup actually
	// inspected after expanding any logical effort aliases (session-resume-*
	// member directories). A named `wb worktree cleanup <effort>` invocation
	// must judge apply success against these identities, not the pre-resolution
	// selector that produced them.
	ResolvedTasks []string `json:"resolved_tasks,omitempty"`
}

type CleanupResult struct {
	ListResult
	Eligible      bool `json:"eligible"`
	Applied       bool `json:"applied"`
	RemoteDeleted bool `json:"remote_deleted"`
	WorktreeGone  bool `json:"worktree_gone"`
	// WorktreeResidueRemoved records that Git unregistered the worktree, failed
	// to finish deleting it, and WB removed what was left. It is audit
	// evidence, not a warning: the task completes either way, and the operator
	// deserves to know which of the two paths deleted the checkout.
	WorktreeResidueRemoved bool   `json:"worktree_residue_removed,omitempty"`
	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
	Initiator    string
	Model        *string
	CLI          *string
	Provider     *string
}

type CreateOptions struct {
	ProjectsRoot string
	Operation    string
	// SessionRequired makes creation an agent-mode mutation: the caller must
	// belong to a live registered WB session before any WB_HOME or Git state is
	// touched. Manual callers leave this false and must record human intent in
	// WorkLog.Initiator when using the CLI's explicit manual mode.
	SessionRequired bool
	// 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 DirtyWorktreeEvidence struct {
	SHA256 string `json:"sha256"`
	Bytes  int64  `json:"bytes"`
	Files  int    `json:"files"`
}

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 ExternalSessionWorkLogPrepareOptions struct {
	ProjectsRoot  string
	Request       sessionmove.Request
	RequestDigest sessionmove.Digest
	ReceivedAt    time.Time
	Session       session.Record
	AttemptID     string
	AttemptIndex  uint64
	WorktreeDir   string
	PinnedCommit  string
	HandoverBytes []byte
	// contains filtered or unexported fields
}

type ExternalSessionWorkLogPrepareResult struct {
	WorkLogReference string            `json:"work_log_reference"`
	ClaimID          string            `json:"claim_id"`
	ReceivedEvent    LocalWorkLogEvent `json:"received_event"`
	OwnerEvent       LocalWorkLogEvent `json:"owner_event"`
	Replayed         bool              `json:"replayed"`
}

type ExternalSourceMessageOptions struct {
	ProjectsRoot   string
	Request        sessionmove.Request
	RequestDigest  sessionmove.Digest
	Receipt        sessionmove.Receipt
	SourceSession  session.Record
	Message        sessionmove.Message
	Record         sessionmove.MessageRecord
	MessageReceipt sessionmove.MessageReceipt
}

type ExternalSourceOfferOptions struct {
	Store         sessionmove.Store
	ExecutionLock *sessionmove.ExecutionLock
	ProjectsRoot  string
	Request       sessionmove.Request
	RequestDigest sessionmove.Digest
	SourceSession session.Record
	// contains filtered or unexported fields
}

type ExternalSourceOfferResult struct {
	OfferEvent LocalWorkLogEvent `json:"offer_event"`
	OwnerEvent LocalWorkLogEvent `json:"owner_event"`
	Replayed   bool              `json:"replayed"`
}

type ExternalSourceSealOptions struct {
	Store         sessionmove.Store
	ExecutionLock *sessionmove.ExecutionLock
	ProjectsRoot  string
	Request       sessionmove.Request
	RequestDigest sessionmove.Digest
	Receipt       sessionmove.Receipt
	SourceSession session.Record
	// contains filtered or unexported fields
}

type ExternalSourceSealResult struct {
	SourceWorkLogReference string            `json:"source_work_log_reference"`
	TargetWorkLogReference string            `json:"target_work_log_reference"`
	SealedAt               time.Time         `json:"sealed_at"`
	CompletionEvent        LocalWorkLogEvent `json:"completion_event"`
	Replayed               bool              `json:"replayed"`
}

type ExternalTargetAttemptFailureOptions struct {
	ProjectsRoot  string
	Request       sessionmove.Request
	RequestDigest sessionmove.Digest
	WorktreeDir   string
	Failure       sessionlaunch.FailureEvidence
}

type ExternalTargetCompletionOptions struct {
	ProjectsRoot  string
	Request       sessionmove.Request
	RequestDigest sessionmove.Digest
	Receipt       sessionmove.Receipt
	WorktreeDir   string
}

type ExternalTargetMessageOptions struct {
	ProjectsRoot  string
	Request       sessionmove.Request
	RequestDigest sessionmove.Digest
	Receipt       sessionmove.Receipt
	Message       sessionmove.Message
	Record        sessionmove.MessageRecord
}

type FetchRemoteCheckpointOptions struct {
	// Root is the repository to fetch into. It need not have any active WB
	// Work Log claim: retrieving another machine's checkpoint is exactly the
	// cross-machine case a claim would not yet exist for.
	Root string
	// Task names the checkpoint ref: refs/wb/checkpoints/<Task>.
	Task string
}

type GCEntry struct {
	Task          string `json:"task"`
	Repository    string `json:"repository"`
	WorktreeDir   string `json:"worktree_dir"`
	WorktreesRoot string `json:"worktrees_root"`
	Branch        string `json:"branch,omitempty"`
	Detached      bool   `json:"detached,omitempty"`
	// Management is managed, unmanaged, or unknown. It decides which command a
	// refusal can honestly name, and it is deliberately three-valued: a
	// checkout with no manifest is *unknown*, not unmanaged, because failing
	// open into a destructive suggestion on missing evidence is exactly the
	// mistake this field exists to prevent.
	Management        string           `json:"management"`
	HeadSHA           string           `json:"head_sha"`
	RemoteHeadSHA     string           `json:"remote_head_sha,omitempty"`
	Class             string           `json:"class"`
	Eligible          bool             `json:"eligible"`
	Applied           bool             `json:"applied"`
	Reason            string           `json:"reason,omitempty"`
	Evidence          []string         `json:"evidence,omitempty"`
	SanctionedCommand string           `json:"sanctioned_command,omitempty"`
	Owner             string           `json:"owner,omitempty"`
	OwnerState        string           `json:"owner_state,omitempty"`
	CreatedAt         time.Time        `json:"created_at,omitempty"`
	AgeSeconds        int64            `json:"age_seconds,omitempty"`
	TTLSeconds        int64            `json:"ttl_seconds,omitempty"`
	Expired           bool             `json:"expired,omitempty"`
	PullRequest       *PullRequest     `json:"pull_request,omitempty"`
	Landing           *LandingEvidence `json:"landing,omitempty"`
	// Warnings carry facts that used to be refusals. A branch renamed since its
	// claim is the one that mattered: refusing on a name check while the same
	// output admits landing evidence is commit-based asked an operator to
	// rename a branch that no longer exists on origin, purely as ceremony.
	Warnings []string        `json:"warnings,omitempty"`
	Size     diskusage.Usage `json:"size,omitempty"`
	Error    string          `json:"error,omitempty"`
}

type GCOptions struct {
	ProjectsRoot string
	Tasks        []string
	Filter       string
	Base         string
	Apply        bool
	// AllowResidue retires a checkout whose work landed but which holds local
	// commits past the landed head, discarding exactly those commits.
	AllowResidue bool
	// SupersededBy is a path to an explicit trusted-reviewer supersession
	// receipt, for an intentionally split branch whose original head never
	// landed as one unit. It is the second of the two widenings the Feature
	// names, and like the first it skips no proof: the receipt must bind the
	// exact source and target heads, classify every residual, and carry a
	// trusted approving actor, all of which the cleanup transaction verifies.
	// It is named-task only and never participates in a fleet sweep.
	SupersededBy string
	// SkipDetached leaves detached checkouts out of the sweep entirely. The
	// default is to include them, because excluding them is the defect.
	SkipDetached bool
	// OlderThan is the merged-pull-request grace window. Zero disables it: gc
	// is evidence-based, and a landing is not more true an hour later.
	OlderThan time.Duration
	// TTL marks checkouts older than this expired in the report. Reporting only.
	TTL time.Duration
	// SessionFreshness is how recently a checkout must have been used for it to
	// count as in use. Beyond it a live process id is presumed recycled and the
	// checkout is classified on its own evidence, with the stale owner named in
	// a warning.
	//
	// Unset means DefaultSessionFreshness, because the failure mode of
	// forgetting this field is deleting a working lane's checkout.
	// DisableSessionFreshness turns the rule off, which is what the CLI's
	// `--session-freshness 0` means — the same spelling as `--older-than 0`.
	SessionFreshness time.Duration
	// ResidueDepth bounds the commit-to-pull-request walk.
	ResidueDepth int
	Workers      int
	// SkipSizes omits the disk measurement. Sizes are measured only for
	// eligible checkouts, because the reclaim footer is the only thing that
	// needs them and walking every refused 1.4 GB node_modules to print a
	// number nobody can act on is exactly the redundant work verbs must not do.
	SkipSizes bool
	Now       func() time.Time
	// DeleteRemote additionally retires an unchanged source branch on origin.
	DeleteRemote bool
	// Progress is passed to the inventory walk.
	Progress func(ListProgress)
}

type GCOutcome struct {
	SchemaVersion int              `json:"schema_version"`
	Apply         bool             `json:"apply"`
	Entries       []GCEntry        `json:"entries"`
	Purged        []PurgedArtefact `json:"purged,omitempty"`
	Diagnostics   []ListDiagnostic `json:"diagnostics,omitempty"`
	// Artifacts is WB's own control-plane residue that is not a checkout: a
	// non-empty quarantined stage, or the empty <task>/<owner>/<repository>
	// husk a removal outside WB leaves behind. Omitting it made gc blind to
	// exactly the debris its own advice creates.
	Artifacts []LifecycleArtifact `json:"artifacts,omitempty"`
	// Shells records the empty task shells this sweep found, planned in a dry
	// run and retired under --apply.
	Shells []RetiredShell `json:"shells,omitempty"`
	// Reclaimable and Reclaimed are always both figures. An apparent size
	// counts hard-linked bytes a deletion will not return; over one measured
	// sweep that was 11.7 GB apparent against 5.9 GB unshared.
	Reclaimable diskusage.Usage `json:"reclaimable"`
	Reclaimed   diskusage.Usage `json:"reclaimed"`
	// PartialTasks names tasks where some repositories retired and others did
	// not, with the repositories left behind. Blocking every repository because
	// one holds residue is correct for a merge and wrong for a cleanup.
	PartialTasks []GCPartialTask `json:"partial_tasks,omitempty"`
	Totals       map[string]int  `json:"totals"`
}

type GCPartialTask struct {
	Task      string   `json:"task"`
	Retired   []string `json:"retired"`
	LeftAlone []string `json:"left_alone"`
}

type GuardOptions struct {
	ProjectsRoot string
	Base         string

	// CheckFreshness performs a point-of-read fetch and exact comparison when
	// guarding a canonical clone. It is opt-in for internal hook callers so a
	// commit or push hook never depends on network availability; the
	// user-facing `wb worktree guard` command enables it.
	CheckFreshness bool

	// 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

	// CheckPublication fetches a linked worktree's own branch and compares it
	// to HEAD, answering the question no Git hook can: after a push, is the
	// commit I am on actually on the remote? Like CheckFreshness it needs the
	// network, so it stays opt-in and no hook depends on it.
	CheckPublication bool
}

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"`
	// TransientOperation names the Git history operation that temporarily
	// detached HEAD. It is empty whenever Transient is false.
	TransientOperation string     `json:"transient_operation,omitempty"`
	Admission          *Admission `json:"admission,omitempty"`
	// External marks a worktree `wb worktree adopt` registered without
	// relocating it under a WB worktrees root — see ListResult.External. Its
	// task was resolved from its own Work Log claim, not from its path.
	External bool `json:"external,omitempty"`
	// Freshness is populated for canonical clones when CheckFreshness is true.
	// A failed fetch is an explicit receipt status, not a reason to weaken the
	// existing checkout safety decision.
	Freshness *CanonicalFreshness `json:"freshness,omitempty"`
	// Publication is populated for linked worktrees when CheckPublication is
	// true: the exact comparison of HEAD with origin/<this worktree's branch>.
	// It reuses the freshness receipt shape because it is the same
	// fetch-and-compare aimed at a different ref.
	Publication *CanonicalFreshness `json:"publication,omitempty"`
}

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

type InterruptedLockRecovery struct {
	Task          string `json:"task"`
	WorktreesRoot string `json:"worktrees_root"`
	Path          string `json:"path"`
	PID           int    `json:"pid"`
	Disposition   string `json:"disposition"`
	Applied       bool   `json:"applied"`
	Reason        string `json:"reason,omitempty"`
}

type LandingEvidence struct {
	// LandedSHA is the newest commit of this branch with a verified landing.
	LandedSHA string `json:"landed_sha"`
	// LandingSHA is the commit in the target that carried the work there.
	LandingSHA string `json:"landing_sha"`
	// PullRequest is the merged pull request GitHub's own commit index named.
	PullRequest *PullRequest `json:"pull_request,omitempty"`
	// Residue is every commit this checkout holds past LandedSHA, newest first.
	// Deleting the branch discards exactly these commits, which is why
	// `--allow-residue` prints them before it widens past them.
	Residue []ResidualCommit `json:"residue,omitempty"`
	// Truncated records that the walk hit its depth bound before finding a
	// landing, so absence of evidence here is not evidence of absence.
	Truncated bool `json:"truncated,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"`
	Repository    string `json:"repository,omitempty"`
	NonBlocking   bool   `json:"non_blocking,omitempty"`
	Disposition   string `json:"disposition"`
	Eligible      bool   `json:"eligible"`
	Applied       bool   `json:"applied"`
	ArchivePath   string `json:"archive_path,omitempty"`
	Reason        string `json:"reason,omitempty"`
}

type LifecycleBacklogQuarantine struct {
	Path       string `json:"path"`
	Task       string `json:"task,omitempty"`
	Repository string `json:"repository,omitempty"`
	Reason     string `json:"reason"`
}

type ListDiagnostic struct {
	Task          string `json:"task,omitempty"`
	WorktreesRoot string `json:"worktrees_root,omitempty"`
	Path          string `json:"path"`
	Message       string `json:"message"`
	// NonBlocking identifies visible foreign filesystem debris that has no
	// corresponding canonical repository. It is never a validated WB asset
	// and must not prevent a real sibling from reaching its own safe terminal
	// transition. Any WB-shaped path remains blocking.
	NonBlocking bool `json:"non_blocking,omitempty"`
}

type ListOptions struct {
	ProjectsRoot string
	Task         string
	// Tasks is an exact set of task names. Task remains for compatibility with
	// callers that select one task; callers must not set both.
	Tasks []string
	// Base is the fallback target branch for candidates without an immutable
	// recorded target. A candidate's manifest/Work Log claim wins over this
	// fallback, so one task may safely contain worktrees stacked on different
	// targets. An omitted Base resolves to main.
	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
	// OwnerState limits results by current owner PID liveness: active or orphaned.
	OwnerState 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
	// Progress, when set, is called as the walk reaches and finishes each
	// candidate. The inventory is one long blocking call — with GitHub set it
	// fetches from the network once per candidate, serially — so without this
	// hook a fleet-wide run is indistinguishable from a hang for as long as it
	// takes. It is observation only: nothing about the walk depends on it, and
	// a nil Progress costs nothing.
	Progress func(ListProgress)
	// Workers caps concurrent candidate inspections, mirroring wb sync's
	// --workers. Zero means the default; one makes the walk serial again,
	// which is the behaviour to fall back to if a repository ever proves
	// unsafe to inspect alongside its siblings.
	Workers int
	// IncludeDetached keeps a checkout whose HEAD is detached in the inventory
	// instead of reporting it as a malformed candidate. A pull-request review
	// checkout is detached by construction, and dropping it from the inventory
	// is why nothing in WB could ever retire one: the measured sweep showed 50
	// inventory rows for 60 checkouts. Callers that mutate a branch — cleanup,
	// merge — leave this false, so a detached checkout stays outside their
	// reach exactly as before; `wb worktree list` and `wb worktree gc` set it.
	IncludeDetached bool
	// TTL, when positive, marks a checkout older than this as expired. It is
	// pure reporting: nothing acts on it, and its purpose is that "this task
	// has been finished for six days" is visible before the disk fills.
	TTL time.Duration
	// Activity asks the inventory to record LastActivityAt. Only a verb that
	// decides whether a checkout may be removed needs it.
	Activity bool
	// ResidueEvidence asks the inventory to look for a landed ancestor when the
	// head itself is not integrated. It costs up to ResidueDepth extra reads of
	// GitHub's commit index per candidate, so it is opt-in: a fleet-wide sweep
	// over dozens of unlanded worktrees must not pay for evidence nobody asked
	// for. Verbs that classify — worktree gc — set it; verbs that merely list
	// do not.
	ResidueEvidence bool
	// ResidueDepth bounds how far back from HEAD that walk goes. Zero uses
	// DefaultResidueDepth.
	ResidueDepth int
	// Now is the clock used for age and TTL. Tests inject it; production
	// leaves it nil for time.Now.
	Now func() time.Time
}

type ListOutcome struct {
	SchemaVersion int                 `json:"schema_version"`
	Results       []ListResult        `json:"results"`
	Diagnostics   []ListDiagnostic    `json:"diagnostics,omitempty"`
	Artifacts     []LifecycleArtifact `json:"artifacts,omitempty"`
	// Purged records the terminal artefacts this read path swept. It is
	// evidence for a receipt, never a per-invocation log line: see
	// purgeTerminalArtefacts.
	Purged []PurgedArtefact `json:"purged,omitempty"`
}

type ListProgress struct {
	// Index counts candidates inspected in this run, 1-based, across every
	// layout. The total is not known in advance: it takes reading each task
	// directory to learn how many repositories are under it, which is most of
	// the walk itself.
	Index      int
	Task       string
	Repository string // empty until inspection identifies it
	Path       string
	// Done distinguishes reaching a candidate from finishing it. Both are
	// reported because the gap between them is the part that takes the time,
	// and a candidate that never reports Done is the one that is stuck.
	Done    bool
	Elapsed time.Duration
	// Network is true when this candidate's inspection contacts origin, which
	// is what makes the walk slow.
	Network bool
}

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"`
	// SupersededAtOrigin records an explicitly reviewed split-branch
	// terminalization. It deliberately does not set IntegratedAtOrigin: the
	// original head did not land as a whole.
	SupersededAtOrigin    bool   `json:"superseded_at_origin,omitempty"`
	SupersessionReceipt   string `json:"supersession_receipt,omitempty"`
	SupersessionReviewer  string `json:"supersession_reviewer,omitempty"`
	SupersessionReceiptID string `json:"supersession_receipt_id,omitempty"`
	SupersessionRejection string `json:"supersession_rejection,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"`
	// LockOwner and LockOwnerPID describe who holds Locked, so a refusal
	// can distinguish a peer operation still running from a recoverable
	// remnant of one that was interrupted. See diagnoseTaskLock.
	LockOwner    LockOwnerState `json:"lock_owner,omitempty"`
	LockOwnerPID int            `json:"lock_owner_pid,omitempty"`
	LastCommit   time.Time      `json:"last_commit"`
	Owners       []OwnerView    `json:"owners,omitempty"`
	// WorkLogSessionID is the immutable session link from the active private
	// claim. It lets session park recover a claim even when the owner event was
	// not projected, while remaining absent for legacy claims.
	WorkLogSessionID  string       `json:"work_log_session_id,omitempty"`
	OwnerState        string       `json:"owner_state"`
	OpenPullRequest   *PullRequest `json:"open_pull_request,omitempty"`
	MergedPullRequest *PullRequest `json:"merged_pull_request,omitempty"`
	// External marks a worktree adopted by `wb worktree adopt` from outside
	// every WB worktrees root. Its WorktreeDir is the real, never-relocated
	// checkout path; only a small registration entry — never the checkout
	// itself — lives under the WB task directory. See openAdoptedCleanupWorktree
	// and locateAdoptedWorktree.
	External bool `json:"external,omitempty"`
	// Detached marks a checkout with no current branch. Branch is empty for
	// one, so every branch-shaped operation must skip it rather than act on an
	// empty ref. It is populated only when ListOptions.IncludeDetached is set.
	Detached bool `json:"detached,omitempty"`
	// Owner is the agent identity that last took custody, or "orphaned" when
	// none is live. It is the human-readable half of OwnerState, carried here
	// so an inventory row can name who to ask before removing anything.
	Owner string `json:"owner,omitempty"`
	// CreatedAt is the immutable manifest's creation time, falling back to the
	// worktree directory's own modification time for a checkout WB did not
	// create. AgeSeconds and Expired are derived from it against ListOptions.TTL.
	CreatedAt  time.Time `json:"created_at,omitempty"`
	AgeSeconds int64     `json:"age_seconds,omitempty"`
	TTLSeconds int64     `json:"ttl_seconds,omitempty"`
	Expired    bool      `json:"expired,omitempty"`
	// HeadUnknownToRemote records that GitHub's commit index has never seen
	// this head: the checkout holds work that was never pushed anywhere.
	HeadUnknownToRemote bool `json:"head_unknown_to_remote,omitempty"`
	// LastActivityAt is the newest sign that anyone is using this checkout:
	// a heartbeat, an edited file, a Work Log event, or a commit. It is what
	// "in use" is decided from, because a live process id is evidence about a
	// process and the question is about a worktree.
	LastActivityAt time.Time `json:"last_activity_at,omitempty"`
	// Landing is the commit-identity landing evidence for a head that is not
	// itself contained in the target: the merged pull request of an ancestor,
	// plus the local commits stacked on top of it. A squash merge produces
	// exactly this shape, and reporting it as a bare "awaiting push" was 7 of
	// 11 refusals in the measured sweep. See landingEvidence.
	Landing *LandingEvidence `json:"landing,omitempty"`
	// contains filtered or unexported fields
}

type LoadWorkLogOptions struct {
	ProjectsRoot        string
	Worktree            string
	IncludePromptBodies bool
}

type LocalGitEvidence struct {
	Branch    string `json:"branch,omitempty"`
	Head      string `json:"head,omitempty"`
	Dirty     bool   `json:"dirty"`
	StatusSHA string `json:"status_sha256,omitempty"`
	Status    string `json:"status,omitempty"`
}

type LocalTargetEvidence struct {
	Ref       string    `json:"ref,omitempty"`
	SHA       string    `json:"sha,omitempty"`
	FetchedAt time.Time `json:"fetched_at,omitempty"`
	Ahead     int       `json:"ahead"`
	Behind    int       `json:"behind"`
	Strategy  string    `json:"strategy,omitempty"`
}

type LocalUsageEvidence struct {
	Discriminator string   `json:"discriminator"`
	InputTokens   *int64   `json:"input_tokens,omitempty"`
	OutputTokens  *int64   `json:"output_tokens,omitempty"`
	TotalTokens   *int64   `json:"total_tokens,omitempty"`
	EstimatedCost *float64 `json:"estimated_cost,omitempty"`
	Currency      string   `json:"currency,omitempty"`
	ProviderRef   string   `json:"provider_ref,omitempty"`
}

type LocalWorkLogEvent struct {
	Version    int                  `json:"version"`
	Seq        int                  `json:"seq"`
	ID         string               `json:"id"`
	Type       string               `json:"type"`
	At         time.Time            `json:"at"`
	Message    string               `json:"message,omitempty"`
	NextAction string               `json:"next_action,omitempty"`
	Prompt     string               `json:"prompt,omitempty"`
	PromptSHA  string               `json:"prompt_sha256,omitempty"`
	Git        *LocalGitEvidence    `json:"git,omitempty"`
	Target     *LocalTargetEvidence `json:"target,omitempty"`
	Usage      *LocalUsageEvidence  `json:"usage,omitempty"`
	Result     string               `json:"result,omitempty"`
	Conflict   string               `json:"conflict,omitempty"`
	Owner      *OwnerRegistration   `json:"owner,omitempty"`
	Extra      map[string]any       `json:"extra,omitempty"`
}

type LocalWorkLogProjection struct {
	Version        int                  `json:"version"`
	EffortID       string               `json:"effort_id,omitempty"`
	RunID          string               `json:"run_id,omitempty"`
	ClaimID        string               `json:"claim_id,omitempty"`
	Lifecycle      string               `json:"lifecycle"`
	LastSeq        int                  `json:"last_seq"`
	LastEventID    string               `json:"last_event_id,omitempty"`
	LastType       string               `json:"last_type,omitempty"`
	LastMessage    string               `json:"last_message,omitempty"`
	LastNextAction string               `json:"last_next_action,omitempty"`
	LastCheckpoint *LocalGitEvidence    `json:"last_checkpoint,omitempty"`
	LastTarget     *LocalTargetEvidence `json:"last_target,omitempty"`
	Conflict       string               `json:"conflict,omitempty"`
	UpdatedAt      time.Time            `json:"updated_at"`
}

type LockOwnerState string

type LogArchiveOptions struct {
	ProjectsRoot string
	Worktree     string
	Apply        bool
	Force        bool
}

type LogCheckpointOptions struct {
	ProjectsRoot  string
	Worktree      string
	Message       string
	NextAction    string
	UsageDisc     string
	InputTokens   *int64
	OutputTokens  *int64
	EstimatedCost *float64
	Currency      string
	ProviderRef   string
	// SkipRemote suppresses the remote checkpoint push, keeping the verb
	// exactly as local-only as it was before this ref namespace existed.
	// Use it offline, on a detached HEAD, or wherever the extra network call
	// is unwanted; the local Work Log checkpoint always still happens.
	SkipRemote bool
}

type LogFinalizeOptions struct {
	ProjectsRoot string
	Worktree     string
	Result       string // success|failure
	Message      string
	Apply        bool
}

type LogHandoffOptions struct {
	ProjectsRoot  string
	Worktree      string
	HandoffID     string
	TargetMachine string
	BundleCommit  string
	Summary       string
	NextAction    string
	Successor     string
	Model         string
	CLI           string
	Provider      string
	Apply         bool
	// EventID/At and lineage fields are optional for ordinary manual verbs.
	// Session checkpoint supplies them to make its offer immutable evidence
	// derivable from the exact request digest.
	EventID                string
	At                     time.Time
	RequestDigest          sessionmove.Digest
	SourceWorkLogReference string
	PredecessorWBSessionID string
	SourceMachine          string
}

type LogInitOptions struct {
	ProjectsRoot string
	Worktree     string
	Prompt       []byte
	Source       string
	Model        string
	CLI          string
	Provider     string
	Runtime      string
	AgentID      string
}

type LogIntegrateOptions struct {
	ProjectsRoot string
	Worktree     string
	Base         string
	Strategy     string // rebase|merge|auto
}

type LogRecoverOptions struct {
	ProjectsRoot string
	Worktree     string
	Apply        bool
	// EstablishClaim is an explicit audited recovery for an internally-created
	// worktree whose immutable manifest predates private claim publication.
	// It never rewrites the manifest or local journal events; it only publishes
	// the missing immutable claim and rebuilds the derived projections.
	EstablishClaim  bool
	Takeover        bool
	Actor           string
	ReconcileBranch string
	ExpectedHead    string
	Remote          bool
	Reason          string
	EventID         string
	// contains filtered or unexported fields
}

type LogRefreshOptions struct {
	ProjectsRoot string
	Worktree     string
	Base         string
}

type LogSteerOptions struct {
	ProjectsRoot string
	Worktree     string
	Body         []byte
	Source       string
	Runtime      string
	Model        string
	CLI          string
	Provider     string
}

type LogSyncOptions struct {
	ProjectsRoot string
	Worktree     string
	Apply        bool
}

type LogVerbResult struct {
	Worktree   string                  `json:"worktree"`
	Verb       string                  `json:"verb"`
	Event      *LocalWorkLogEvent      `json:"event,omitempty"`
	Projection *LocalWorkLogProjection `json:"projection,omitempty"`
	Prompt     string                  `json:"prompt,omitempty"`
	Applied    bool                    `json:"applied"`
	Offline    bool                    `json:"offline,omitempty"`
	Outbox     int                     `json:"outbox,omitempty"`
	Notes      []string                `json:"notes,omitempty"`
	Diagnosis  []string                `json:"diagnosis,omitempty"`
	// RemoteCheckpoint is set only by the checkpoint verb, and only when a
	// remote push was attempted. Its Notice field always carries
	// NotALandingReceiptNotice: a remote checkpoint is a durability aid,
	// never proof that the checkpointed task landed anywhere.
	RemoteCheckpoint      *RemoteCheckpointResult `json:"remote_checkpoint,omitempty"`
	ReadyForNormalCleanup bool                    `json:"ready_for_normal_cleanup,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"`
	DependencyCampaign bool      `yaml:"dependency_campaign,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 MergeReceiptCleanupProof struct {
	Repository     string
	Target         string
	SourceTask     string
	SourceWorktree string
	SourceBranch   string
	SourceSHA      string
	CandidateSHA   string
	LandingSHA     string
}

type OriginalPromptView struct {
	Source string `json:"source"` // journal | archive
	Name   string `json:"name,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
	Body   string `json:"body,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"`
	// Residue is the checkouts no registry mentions, which the family sweep is
	// structurally unable to see. See orphans_residue.go.
	Residue   []OrphanResidue `json:"residue,omitempty"`
	Totals    OrphanTotals    `json:"totals"`
	Unscanned []string        `json:"unscanned,omitempty"`
}

type OrphanResidue struct {
	Path          string   `json:"path"`
	WorktreesRoot string   `json:"worktrees_root"`
	Task          string   `json:"task"`
	Repository    string   `json:"repository"`
	Layout        string   `json:"layout"`
	CanonicalDir  string   `json:"canonical_dir,omitempty"`
	Evidence      []string `json:"evidence,omitempty"`
	Remedy        string   `json:"remedy"`
}

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"`
	Residue     int            `json:"residue"`
}

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

	// Owner evidence, when a session declared itself. OwnerState is live,
	// gone, or unstated; only a declared PID counts, so a worktree nobody
	// claimed is unstated rather than falsely reported as abandoned.
	OwnerState string `json:"owner_state"`
	OwnerAgent string `json:"owner_agent,omitempty"`
	OwnerPID   int    `json:"owner_pid,omitempty"`

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

type OwnerRegistration struct {
	Agent     string `json:"agent,omitempty"`
	Model     string `json:"model,omitempty"`
	Effort    string `json:"effort,omitempty"`
	Initiator string `json:"initiator,omitempty"`
	// PID is the declared agent session's process, never WB's own. WB is a
	// short-lived CLI: its PID is dead moments after it would be written, and
	// once recycled it would report an abandoned worktree as active. An
	// absent PID therefore reads as unknown, which is the honest answer.
	PID int `json:"pid,omitempty"`
	// WBVersion and Command are always populated, because WB always knows
	// them. They give a worktree provenance even when no agent identity was
	// declared.
	WBVersion string    `json:"wb_version,omitempty"`
	Command   string    `json:"command,omitempty"`
	At        time.Time `json:"at"`
}

type OwnerView struct {
	OwnerRegistration
	PIDStatus string `json:"pid_status"`
}

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

type ParkedLocalSuccessorOptions struct {
	ProjectsRoot string
	Bundle       sessionpark.Bundle
	Successor    session.Record
	AttemptID    string
	AttemptIndex uint64
}

type ParkedSessionWorkLogPrepareOptions struct {
	ProjectsRoot  string
	Request       sessionpark.RemoteRequest
	RequestDigest sessionmove.Digest
	Member        sessionpark.RemoteMember
	ReceivedAt    time.Time
	Session       session.Record
	AttemptID     string
	AttemptIndex  uint64
	WorktreeDir   string
	PinnedCommit  string
}

type ParkedSessionWorkLogPrepareResult struct {
	WorkLogReference string
	ClaimID          string
	ReceivedEvent    LocalWorkLogEvent
	OwnerEvent       LocalWorkLogEvent
	Replayed         bool
}

type ParkedTargetCompletionOptions struct {
	ProjectsRoot  string
	Request       sessionpark.RemoteRequest
	RequestDigest sessionmove.Digest
	Member        sessionpark.RemoteMember
	WorktreeDir   string
	Successor     sessionlaunch.Result
	// contains filtered or unexported fields
}

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 PromptRecord struct {
	Name     string    `json:"name"`
	Seq      int       `json:"seq"`
	At       time.Time `json:"at"`
	SHA256   string    `json:"sha256"`
	Source   string    `json:"source"`
	Runtime  string    `json:"runtime,omitempty"`
	Model    string    `json:"model,omitempty"`
	CLI      string    `json:"cli,omitempty"`
	Provider string    `json:"provider,omitempty"`
	Body     string    `json:"body,omitempty"`
}

type PullRequest struct {
	Number     int        `json:"number"`
	URL        string     `json:"url"`
	Repository string     `json:"repository,omitempty"`
	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 PurgedArtefact struct {
	Task          string `json:"task"`
	WorktreesRoot string `json:"worktrees_root"`
	Path          string `json:"path"`
	Kind          string `json:"kind"`
}

type PushRemoteCheckpointOptions struct {
	// Root is the repository worktree to push from.
	Root string
	// Task names the checkpoint ref: refs/wb/checkpoints/<Task>.
	Task string
	// HeadSHA is the exact commit to publish. The caller resolves it before
	// calling so the pushed object is never ambiguous.
	HeadSHA string
}

type RemoteCheckpointFetchResult struct {
	Ref      string `json:"ref"`
	SHA      string `json:"sha"`
	LocalRef string `json:"local_ref"`
	Notice   string `json:"notice"`
}

type RemoteCheckpointResult struct {
	Ref    string `json:"ref"`
	SHA    string `json:"sha"`
	Pushed bool   `json:"pushed"`
	Notice string `json:"notice"`
}

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 ResidualCommit struct {
	SHA     string `json:"sha"`
	Subject string `json:"subject"`
}

type RetireShellsOptions struct {
	ProjectsRoot string
	Filter       string
	Apply        bool
	// Tasks limits the sweep to these exact task names. Empty sweeps every
	// task, which is what `wb worktree cleanup --retire-shells` wants; a caller
	// acting on one named task must not quietly retire shells across the fleet
	// on its behalf.
	Tasks []string
}

type RetireShellsOutcome struct {
	Apply   bool           `json:"apply"`
	Results []RetiredShell `json:"results"`
	Totals  map[string]int `json:"totals"`
}

type RetiredShell struct {
	WorktreesRoot string `json:"worktrees_root"`
	Task          string `json:"task"`
	Path          string `json:"path"`
	Eligible      bool   `json:"eligible"`
	Applied       bool   `json:"applied"`
	Reason        string `json:"reason"`
	Error         string `json:"error,omitempty"`
}

type RetiredStageRecoveryOptions struct {
	ProjectsRoot string
	Task         string
	Stage        string
	Apply        bool
}

type RetiredStageRecoveryOutcome struct {
	Apply       bool                         `json:"apply"`
	ReceiptPath string                       `json:"receipt_path,omitempty"`
	Results     []RetiredStageRecoveryResult `json:"results"`
}

type RetiredStageRecoveryResult struct {
	WorktreesRoot string `json:"worktrees_root"`
	Task          string `json:"task"`
	Path          string `json:"path"`
	Stage         string `json:"stage"`
	GitRepository string `json:"git_repository,omitempty"`
	GitDir        string `json:"git_dir,omitempty"`
	Branch        string `json:"branch,omitempty"`
	HeadSHA       string `json:"head_sha,omitempty"`
	RemoteURL     string `json:"remote_url,omitempty"`
	ContentDigest string `json:"content_digest"`
	FileCount     int    `json:"file_count"`
	ByteCount     int64  `json:"byte_count"`
	SymlinkCount  int    `json:"symlink_count,omitempty"`
	StageDevice   uint64 `json:"stage_device,omitempty"`
	StageInode    uint64 `json:"stage_inode,omitempty"`
	Durable       bool   `json:"durable"`
	Eligible      bool   `json:"eligible"`
	Applied       bool   `json:"applied"`
	ArchivePath   string `json:"archive_path,omitempty"`
	Disposition   string `json:"disposition"`
	Reason        string `json:"reason"`
}

type SessionCheckpointOptions struct {
	ProjectsRoot         string
	Worktree             string
	SourceSession        session.Record
	TargetMachine        string
	RequestedHarness     string
	HandoffID            string
	SuccessorWBSessionID string
	Handover             SessionHandover
	Now                  time.Time
	// contains filtered or unexported fields
}

type SessionCheckpointResult struct {
	Request       sessionmove.Request `json:"request"`
	Digest        sessionmove.Digest  `json:"request_digest"`
	RequestBytes  []byte              `json:"-"`
	HandoverBytes []byte              `json:"-"`
	WorkLogEvent  LocalWorkLogEvent   `json:"work_log_event"`
}

type SessionHandover struct {
	Summary            string
	ValidationEvidence string
	RemainingWork      string
	Body               []byte
}

type SessionMemberReceiveOptions struct {
	ProjectsRoot string
	Spec         SessionReceiveSpec
}

type SessionReceiveOptions struct {
	ProjectsRoot  string
	Request       sessionmove.Request
	RequestDigest sessionmove.Digest
	// ExecutionLock is the already-held per-handoff receiver fence. Its
	// exact admitted Store/request authority can authorize recovery of this
	// handoff's interrupted worktree operation; ordinary direct callers and
	// locks from another Store remain fail-closed.
	ExecutionLock *sessionmove.ExecutionLock
	// contains filtered or unexported fields
}

type SessionReceiveResult struct {
	Repository    string `json:"repository"`
	CanonicalDir  string `json:"canonical_dir"`
	WorktreeDir   string `json:"worktree_dir"`
	Commit        string `json:"commit"`
	HandoverBytes []byte `json:"-"`
	Reused        bool   `json:"reused"`
}

type SessionReceiveSpec struct {
	AuthorityID      string
	AuthorityDigest  sessionmove.Digest
	AuthorityStore   string
	Fence            sessionauthority.Fence
	OperationID      string
	MemberKey        string
	RepositoryRemote string
	Branch           string
	Commit           string
	PinBranch        string
	SourceWorkCommit string
	HandoverPath     string
	HandoverDigest   sessionmove.Digest
}

type SupersessionApproval struct {
	Actor      string    `json:"actor"`
	Trusted    bool      `json:"trusted"`
	Decision   string    `json:"decision"`
	ReceiptID  string    `json:"receipt_id"`
	ApprovedAt time.Time `json:"approved_at"`
}

type SupersessionDependencyDelta struct {
	SourcePR         string `json:"source_pr"`
	SourceHead       string `json:"source_head"`
	Consumer         string `json:"consumer"`
	Ecosystem        string `json:"ecosystem"`
	Package          string `json:"package"`
	Manifest         string `json:"manifest"`
	Selector         string `json:"selector"`
	Before           string `json:"before"`
	RequestedAfter   string `json:"requested_after"`
	CandidateAfter   string `json:"candidate_after"`
	Lockfile         string `json:"lockfile,omitempty"`
	LockfileSelector string `json:"lockfile_selector,omitempty"`
	LockfileVersion  string `json:"lockfile_version,omitempty"`
	Reviewed         bool   `json:"reviewed"`
}

type SupersessionReceipt struct {
	Version           int                       `json:"version"`
	Repository        string                    `json:"repository"`
	Task              string                    `json:"task"`
	Branch            string                    `json:"branch"`
	OriginalHead      string                    `json:"original_head"`
	Target            string                    `json:"target"`
	TargetHead        string                    `json:"target_head"`
	Replacements      []SupersessionReplacement `json:"replacements"`
	Residuals         []SupersessionResidual    `json:"residuals"`
	ResidualsComplete bool                      `json:"residuals_complete"`
	Approval          SupersessionApproval      `json:"approval"`
	// OriginalPR identifies the source pull request when this is a dependency
	// consolidation. A PR-scoped receipt opts into exact dependency proof;
	// generic worktree supersessions leave it empty.
	OriginalPR               string                        `json:"original_pr,omitempty"`
	OriginalPRNumber         int                           `json:"original_pr_number,omitempty"`
	OriginalPRRepository     string                        `json:"original_pr_repository,omitempty"`
	OriginalPRHead           string                        `json:"original_pr_head,omitempty"`
	DependencyDeltasComplete bool                          `json:"dependency_deltas_complete,omitempty"`
	DependencyDeltas         []SupersessionDependencyDelta `json:"dependency_deltas,omitempty"`
}

type SupersessionReplacement struct {
	Kind string `json:"kind"` // pr or commit
	Ref  string `json:"ref"`
	SHA  string `json:"sha,omitempty"`
}

type SupersessionResidual struct {
	Commit         string   `json:"commit"`
	Classification string   `json:"classification"` // replaced, obsolete, regressive, or cosmetic
	Reason         string   `json:"reason"`
	ReplacementRef string   `json:"replacement_ref,omitempty"`
	Paths          []string `json:"paths,omitempty"`
	Reviewed       bool     `json:"reviewed"`
}

type TerminalWorkLogExpectation struct {
	Task        string
	Repository  string
	Worktree    string
	Branch      string
	Base        string
	FinalCommit string
}

type WorkLogClaimView struct {
	EffortID        string    `json:"effort_id"`
	RunID           string    `json:"run_id"`
	ClaimID         string    `json:"claim_id"`
	Task            string    `json:"task,omitempty"`
	Repository      string    `json:"repository"`
	Worktree        string    `json:"worktree"`
	Branch          string    `json:"branch"`
	Base            string    `json:"base"`
	BaseSHA         string    `json:"base_sha"`
	Lifecycle       string    `json:"lifecycle"`
	RecordedAt      time.Time `json:"recorded_at"`
	Initiator       string    `json:"initiator,omitempty"`
	AgentID         string    `json:"agent_id,omitempty"`
	AgentRuntime    string    `json:"agent_runtime,omitempty"`
	Model           string    `json:"model,omitempty"`
	ModelProvenance string    `json:"model_provenance,omitempty"`
	CLI             string    `json:"cli,omitempty"`
	Provider        string    `json:"provider,omitempty"`
	PromptDigest    string    `json:"prompt_sha256,omitempty"`
	PromptArchive   string    `json:"prompt_archive,omitempty"`
	ClaimPath       string    `json:"claim_path,omitempty"`
}

type WorkLogGitEvidence struct {
	Branch string `json:"branch,omitempty"`
	Head   string `json:"head,omitempty"`
	Dirty  bool   `json:"dirty"`
	Status string `json:"status_short,omitempty"`
}

type WorkLogOptions struct {
	EffortID     string
	RunID        string
	Initiator    string
	AgentID      string
	AgentRuntime string
	Model        string
	CLI          string
	Provider     string
	// WBSessionID links this claim to the live registered session that created
	// it. Normal callers leave it empty and the current resolver supplies it.
	WBSessionID           string
	OriginalPrompt        string // readable local file, copied to the private archive
	RequireOriginalPrompt bool   // public create/recycle commands require exact local recovery input
	// AcquiredVia records how this claim came to exist when it is not an
	// ordinary `wb worktree create`. "adopted" marks a claim written for a
	// pre-WB worktree by `wb worktree adopt`, so the claim itself — not just
	// the manifest beside it — says the identity was reconstructed rather than
	// created. Empty for a normal create.
	AcquiredVia string
	// 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
}

type WorkLogView struct {
	Worktree       string              `json:"worktree"`
	Manifest       *Manifest           `json:"manifest,omitempty"`
	Prompts        []PromptRecord      `json:"prompts"`
	OriginalPrompt *OriginalPromptView `json:"original_prompt,omitempty"`
	Claim          *WorkLogClaimView   `json:"claim,omitempty"`
	Owners         []OwnerView         `json:"owners,omitempty"`
	Git            WorkLogGitEvidence  `json:"git"`
	Notes          []string            `json:"notes,omitempty"`
}