Add purpose-owned disposable worktree lifecycle

[chubes4]

Problem

DMC cannot represent why a managed worktree exists or who owns its terminal cleanup. Worktree creation persists generic origin/task attribution but no purpose, owner run, disposition, or completion policy. Every checkout starts active and remains there unless a caller separately remembers to finalize it.

This produces persistent ghost worktrees when an automation workflow creates a clean checkout for one operation, especially release staging. The current inventory contains 14 managed release*/recover* worktrees: nine are stale active, three have no lifecycle metadata, and only one is cleanup eligible. Four additional linked worktrees check out literal default branches and are stale active.

Literal main/trunk linked worktrees are additionally protected by full cleanup as protected_base_branch_worktree, even when they were explicitly created as disposable operation staging.

Root cause

• workspace worktree add accepts branch/base/task attribution but no generic lifecycle intent.
• Initial metadata has no purpose, owner_run_ref, or cleanup_policy.
• Cleanup cannot distinguish disposable operation staging from durable task work.
• Generic Git containment can prove an empty branch is merged, but cannot prove the owning operation is terminal.
• Explicitly terminal disposable linked worktrees on protected branch names lack a first-class safe removal contract.

Required generic contract

Extend managed worktree lifecycle metadata with optional, product-agnostic intent:

• purpose: opaque stable caller-owned label, such as release_staging.
• owner_run_ref: durable opaque reference to the workflow/run that owns terminal disposition.
• cleanup_policy: typed policy describing terminal behavior, initially manual, remove_on_success, or preserve_on_failure.

Creation, exact-handle reuse, inventory, remote backend projection, list output, and lifecycle reconciliation must preserve these fields. Reuse must require compatible intent rather than silently adopting a checkout owned by another run.

Finalization must accept an owner-terminal outcome and convert eligible disposable worktrees to cleanup eligibility without treating finalizer/scanner bookkeeping as fresh user activity. A linked protected-branch checkout may be removed only when all of these hold:

• It is not the authoritative primary checkout.
• Explicit owner-terminal metadata authorizes cleanup.
• The worktree is clean and has no unpushed commits.
• No live owner/process evidence remains.
• Path containment and branch identity checks pass.

Migration visibility

Add a bounded report for likely legacy operation-staging ghosts using evidence such as release/recover naming, stale lifecycle, clean state, pushed/default-contained history, and non-primary location. This is review evidence, not automatic semantic inference.

Acceptance criteria

• Ability, CLI, and persisted schemas round-trip all intent fields.
• Existing callers that omit intent retain current behavior.
• Reuse rejects incompatible owner/purpose/policy with a typed reason.
• Terminal disposable finalization becomes immediately removable by bounded cleanup; scanner timestamps do not restart retention.
• Explicit terminal evidence can safely remove a linked main worktree while primary/default protections remain intact for ordinary worktrees.
• Dirty, unpushed, live, primary, branch-identity, and containment protections remain fail-closed.
• Tests cover local and remote workspace records, reuse, finalization, cleanup, and legacy metadata.
• Documentation defines caller ownership: the creating workflow must finalize every terminal outcome.

Related

• Retention recent_activity protection is fed by the scanner's own heartbeat, deadlocking cleanup #886
• Cleanup planning and bounded safety scans regress on large workspaces #948
• cleanup aggregate overruns provider deadlines and hangs without partial results homeboy#10963

AI assistance

• AI assistance: Yes
• Model: OpenAI GPT-5.6 Sol
• Tool: OpenCode
• Used for: runtime inventory analysis, source tracing, contract design, and issue drafting