Existing and product PR worktrees

Part of the reintegration policy. Its Markdown source preserves the detailed contract for this domain.

PR-backed integration

The caco pr namespace has three separate workflows. caco pr close --pr <N> [--project <project>] is the canonical explicit-close path: it re-reads exact provider state, head, and base before one provider close. A provider merge is not explicit close, and an already-closed PR is an idempotent no-op.

Ordinary project PR source updates

A running worker uses caco pr checkout <N> [--project <project>] to open an isolated checkout under its owning agent directory and outside the managed Git root, without spawning or adopting the historical author's runtime. Fresh defaults and operation records stay outside that repository; existing registered legacy paths are retained rather than relocated, and unregistered legacy evidence refuses a parallel default. Explicit launch options retain the new-agent path and its github_integration.enabled opt-in. caco pr adopt --pr <N> is also supported; --bead-id is optional attribution, not a transfer of the original author's claim.

The CLI authenticates the actual project-scoped agent against the daemon's configured head and target repositories; node credentials and a different project/actor are refused. Each worker owns its own checkout metadata, not a project-wide exclusive PR registry. Dirty files and unpublished commits in original checkouts remain untouched; ordinary source work needs no cleaning, upstream repair, old-owner liveness check, controller interaction, or hand-carried receipt. The bounded clone/partial-resume machinery and immediate-parent topology checks still apply.

After editing and committing, use caco pr push --worktree <path>. It checks actual origin, open PR identity, branch, cleanliness, ancestry, and remote head, then publishes the immutable commit with a Git head lease to the same branch/PR. Fetch and merge/rebase concurrent changes normally, resolve conflicts, and retry; another project worker's publication requires no ownership transfer. The publisher creates no replacement PR for changed authorship and invokes no second queue actor. The selected queue and required checks own delivery: a successful source push is not target-branch merge or bead completion.

Default/shared/provider refs, administrative merges, lifecycle transfers, and privileged non-fast-forward recovery are not granted by this source path.

Privileged repair adoption

caco pr adopt --repair retains its controller/transfer authorization, exact receipt, lease, and preservation requirements. It is not a prerequisite for ordinary project-authorized source updates.

Repair adoption re-reads live PR identity immediately before issuing its receipt, resolves the base OID from the configured PR-target remote, and records provider-projection and local-tracking freshness independently. For the configured root target, a stale provider base OID is diagnostic rather than checkout authority; provider base-ref races, configured-target mismatches, true apply-time retargets, provider outages, and stale receipts remain distinct typed refusals.

• Command: Use the existing caco pr adopt --repair --project <project> --agent-id <owner> --bead-id <bead> --pr <number> --expected-head <sha> --repair-reason <reason> --dry-run and apply with its exact --adoption-receipt; there is no arbitrary-base override.
• Delegation: An authorized controller delegates the single publication-writer role with caco bd transfer-ownership --project <project> --bead-id <bead> --to <project>:<worker> --expect-owner <previous> --expect-generation <generation> --pr <number> --head <head> --reason <reason>. The durable canonical transfer allows the new worker to adopt the repair itself without discarding or impersonating the previous worker, and without approval for every edit. The complete provenance and generation bind the receipt and are checked again at mutation/publication. A separate repair registry and checkout preserve the historical registry and all dirty or unpublished original work. Ordinary claims without the exact transfer binding do not acquire this authority.
• Apply: Apply fetches the receipt-bound base from that configured target into origin/<base> alongside the exact source ref and verifies both refs before declaring the head-scoped checkout ready. It never switches, merges, rebases, rewrites the adopted head, or mutates provider state.
• Older checkouts: An exact clean completed repair checkout created by an older binary may consume a fresh controller-authorized receipt to self-heal only its missing required ref and head-scoped repair metadata in place, leaving adoption provenance and checkout HEAD unchanged. A clean pre-metadata standalone repair clone whose operation record was lost can be identified from its exact repair registry; caco pr status previews the recovery and caco pr clean --delete --yes preserves both registry evidence and a durable cleanup audit.
• Next step: Its JSON result carries the mode-less caco agent reintegrate --project <project> --checkout <path> --dry-run --json next command. caco pr status --worktree <repair-path> verifies the supplied repair checkout and registry directly; if canonical regeneration removed an older managed or historical worktree registration, status reports that preserved path as unavailable instead of following it or failing the healthy repair checkout.

Adopted publication acquires canonical bead-scoped custody on the authoritative board node, in addition to local checkout and PR locks. Ownership transfer and explicit ownership/status mutations refuse active or indeterminate publication; a different registry on another node cannot create a second writer. Definite publication or provider refusal releases custody; process loss never silently expires it.

• Inspect and reconcile: caco pr repair-custody --worktree <path> inspects the retained operation. --reconcile retires exact current-worker/generation custody only after provider readback confirms its published head, or its unchanged previous head with affirmative first-party no-active-Git evidence and no operation markers under both local locks. Reconciliation is idempotent, retains audit evidence, and never retries a push, changes CI, or accepts unrelated drift.
• Current limits: Initially only a directly authenticated scoped worker on the authoritative board node is accepted; cross-node and independent-Git routing return authenticated_repair_delegation_required without forwarding or acquiring custody. Node authentication and unsigned provenance headers do not establish an original worker; authenticated delegation under remains the cross-node rollout prerequisite.
• Rollout: Deploy compatible CLI and canonical/forwarding daemons together; older binaries must be quiesced before delegation because they do not participate in custody. Automatic board failover is refused with replicated_repair_custody_required until custody is replicated; initial custody is daemon-local durable state, not a bead field. Preserve active records during manual board-authority migration. Source publication alone does not enable this capability on an older fleet.

Register metadata for an existing source-only PR

caco pr reconcile-metadata was removed in existing PRs no longer need metadata registration.

Continue an already-published generic product

For the configured native-auto-merge lane, managed and owned product checkouts use the same actions: non-force push of the owner's branch, open or reuse its PR, and arm native squash auto-merge on the pushed head. caco pr push and mode-less caco agent reintegrate --project <project> --checkout <path> use GitHub's current state; an unpublished product needs no preliminary registration or preview receipt. A read-only preview reports native_pr_actions without reading a cached target commit or writing a ledger.

Recorded base_head, generation-scope diffs against tracking refs, local PR snapshots, checkout receipts and landing journals do not gate these actions. Task attribution can change without transferring branch ownership. The source branch must belong to the authenticated worker; Git rejects non-fast-forward pushes without a force fallback.

The protected pr merge --auto --squash --match-head-commit <head> command retains required GitHub checks and never uses an admin merge. Already-armed PRs need no second arm; GitHub-confirmed merge is distinct from accepted auto-merge. A failed provider read is unknown, not an absent PR or successful action; lost replies are resolved by provider readback, not a local attempt ledger.

Drafts remain pending review, and review never requests a merge. Other configured landing backends and privileged repair custody retain their contracts; native publication does not select another queue or acquire another worker's branch.

For a published-unjoined product operation, the owner stays blocked on the typed completion blocker and retries its own completion after the cause is fixed (see Completion blockers). The retry reuses the original PR, source head, source bead and idempotency key. It never publishes another generation, substitutes another owner, or accepts a changed project, repository, base, dirty source or removed assignment.

Native auto-merge updates the owned source branch and reuses its open PR. caco pr init remains the distinct separate product-PR worktree flow for another repository or base: it writes deterministic sibling partial-init metadata before bounded clone/fetch/checkout, records phase/PID/attempt/error under one sub-client deadline, and resumes an exact matching dead/failed operation on retry or --resume. Default sibling placement requires a path-free --name; use --branch for namespaced refs or an explicit --worktree to retain an existing recorded path.

• Acquisition: An identity-equivalent configured SSH remote uses raw Git for acquisition so a transient gh repo clone GraphQL failure cannot block materialization; missing, HTTPS-only, forked, or identity-mismatched topology retains the provider-aware gh path. caco pr status --worktree <path> reports recorded partial liveness plus the exact resume command; legacy metadata-less Git clones are read-only and receive no-delete recovery guidance.
• Source selection: pr init --bead-id <source-bead> selects an explicitly owned source child without changing the spawn environment or borrowing an unfinished parent. Canonical ownership is checked before init writes; publication still revalidates it. The operation, metadata and resume command retain that bead, and a changed resume binding refuses. Omitting the option preserves legacy spawn attribution or a beadless product; it does not retroactively bind an existing null-bound checkout or register an external publication.
• Pruning: caco prune pr-checkouts [--project <p>] lists every product or adopted PR worktree under agent roots, including a running agent's, with owner, PR, provider state, apparent size and an eligibility reason. A clean worktree is eligible when its PR is merged or closed with no local commits beyond the PR head, or when it never opened a PR, its remote branch is gone and HEAD adds nothing beyond its base. Dirt, an open PR, a live Git lock or process, a metadata/path mismatch or unknown provider state preserves it; --delete --yes revalidates each eligible worktree and removes it through caco pr clean. Sizes are apparent bytes, so the physical reclaim can be smaller.
• Daily use: Once ready, apply, push, and sync-main operate only on that product worktree and keep Cacophony operational state out of the product PR.
• Drafts are exceptional: Publish ready-for-review by default with caco pr push --title "..." --body-file body.md. Drafts are only for source that must not merge yet: explicit operator-requested review/RFC, experiments, or projects whose integration.default_intent is upstream_draft_pr. Pending parent/umbrella acceptance, unrelated CI, or live acceptance are not reasons to draft. --draft requires a non-empty, single-line --draft-reason before any push unless the project intent supplies the reason. The reason is retained as Cacophony-Draft-Reason: in the body, local publication metadata and JSON receipt. PR listings expose drafts with their reasons, including missing or unavailable reasons. Product pushes require matching draft intent for an existing draft; adopted pushes reject draft flags and preserve metadata. Changing existing PR readiness remains a separate owner decision.
• Product metadata: Products publish their branch with no generation metadata, and no publication metadata claims queue admission.

An unpublished one-path merge partial has distinct local recovery provenance, binding owner, metadata, heads, base, index, paths and content without fabricating a PR or published head. Its exact receipt permits resume/abort, including abort of an unresolved conflict; an interrupted mutation requires receipt-only readback before retry, and the original partial remains preserved. Published recovery retains its existing PR/provider checks, and neither recovery route publishes.