Reintegration policy and recovery guide

Domain pages

• Publication topology and local merge — Markdown source
• PR delivery and generations — Markdown source
• Existing and product PR worktrees — Markdown source
• Reintegration recovery and emergency levers — Markdown source
• Validation and agent closeout — Markdown source
• Recorded summary state artifacts — Markdown source

This guide expands the normative contract in cacophony-spec §17 for operators, profile authors, and managed agents. Agents land work through first-party lifecycle commands so the daemon can preserve branch safety, recorded summaries, and bead state.

Delivery model

• Work lands through GitHub pull requests with native auto-merge: the lifecycle commands push the owner's branch, open or reuse one PR, and arm squash auto-merge (PR delivery).
• Branch protection and CI own validation; for Cacophony the only required check is Check & Lint, and there is no daemon reintegration gate.
• Projects configured for pr_submit publish one ready PR and stop; projects on backend: local_merge keep the isolated publish-or-refuse squash merge.
• The merge, land and hosted queues and the Cara queue engine are retired, and their daemon routes are deleted.
• Retirements follow the feature-removal playbook: stop the behaviour and keep the wire shape first, then remove the shape once old clients have moved.

Canonical lifecycle surface

Agent checkouts come from checkout_type: the default clone is a single-branch clone of the daemon's canonical checkout that borrows its objects, while full clones the project's configured remote with its own object store and needs no canonical checkout. caco git clone --project <name> --into <dir> makes the same config-shaped clone by hand, applying the project's remote, SSH key, identity, git.config and extra remotes; see Agents.

Manual git reset, git cherry-pick, raw pushes to main, or hand-edited daemon checkout history are exceptional diagnostics, not normal reintegration workflow.

Recovery, forensics, and emergency levers

Completion blockers (publication and admission failures that block the owning agent loudly), emergency HTTPS land, and audited self-owned GitHub recovery are in Reintegration recovery.

Canonical checkout and live-config guardrail

Managed workers must not edit ~/.cacophony/config.yaml, $CACOPHONY_DIR/config.yaml, or $CACOPHONY_DIR/daemon/checkouts/<project> to repair live project config, profile composition, or canonical checkout drift. Those paths are live daemon/operator inputs: project config and source changes belong in a managed agent checkout and must land through the lifecycle surface above. If a canonical checkout is stale, dirty, locally ahead, has a broken HEAD or an index lock, or blocks reintegration, preserve the command output and dirty-path evidence, then coordinate with caco-ctrl / the operator-owned recovery path. Workers must not run git reset, git clean, reclone, remove locks, rewrite refs, or hand-write home config as a shortcut.

The fleet config checkout, daemon/checkouts/cacophony-config, is not managed like a product canonical checkout. The daemon's config refresher fetches it about once a minute, validates each fetched commit before checking it out, and keeps the last good commit when a candidate is invalid; local edits there are discarded. Config changes land only as merged cacophony-config pull requests.

For read-only triage, caco ops check --project <name> --json reports local and cluster canonical-checkout freshness, dirty paths, lock state, broken Git state, and owner/action guidance; operator_choice_required or blocked findings are stop signs for ordinary workers — evidence to route, not permission to clean the checkout.

• SSH over port 443: With a configured SSH identity and a default-port GitHub SSH remote, the daemon's repo-owned Git command routes clone/fetch/push through ssh.github.com:443, so reintegration and checkout refresh need neither operator-global SSH config nor a network permitting github.com:22. If that endpoint accepts TCP but closes the handshake while the same deterministic identity works on the default endpoint, checkout refresh and direct reintegration fetches — canonical preflight and the later isolated integration-checkout fetch alike — retry without the HostName ssh.github.com / Port 443 override and persist the working command, so a green preflight is never followed by a raw fetch that reselects the flaky request-level override.
• Explicit URLs: Operators may spell the URL as ssh://git@ssh.github.com:443/<owner>/<repo>.git for remote and every remotes.<name>.url on a port-22-blocked network; avoid ssh://git@github.com:443/..., since the endpoint is ssh.github.com.
• Opting out: If a host reaches the default endpoint but repeatedly fails through ssh.github.com:443, set github_ssh_routing: default_port on that node, or project-wide when appropriate (values auto, ssh_over_443, default_port; node policy wins over project policy), instead of editing checkout-local core.sshCommand.