Reintegration recovery and emergency levers

These recovery, forensic, and emergency-lever contracts accompany the reintegration policy; both expand cacophony-spec §17. Ordinary landing stays on the first-party lifecycle surfaces documented there, and every lever below is operator/controller scoped, audited, and never a routine reintegration path.

Completion blockers

There is no reintegration failure ledger and no reconcile ceremony. When caco agent complete or caco agent reintegrate cannot publish the owner's work, the command fails loudly and the owning agent stays alive in state blocked.

The error and the agent record carry one typed completion_blocker: a stable code, the PR, the exact head and base, the exact provider or Git message, the next supported action, and the owner's retry command. caco agent status, the agent_completion_blocked feed event, and the agents.completion_blocked finding in caco ops status show the same blocker. The project controller is told once per code, PR, and head; a repeated refusal of the same generation does not notify again.

Codes include merge_conflict, structural_conflict, stale_target, post_verification, and git_index_lock.

caco agent status --id <agent>        # the blocker, its cause and next action
caco agent complete --id <agent>      # the owner's retry once the cause is fixed

The owner fixes the cause and retries its own completion. A retry of the same generation reuses the existing PR at the same head and never mints a new generation; a change that needs a new commit is an ordinary new generation. A successful retry clears the blocker and continues the normal lifecycle. A blocked agent cannot self-retire around its blocker; it asks the controller when the cause is outside its authority, and the controller routes it.

Daemons that still held rows of the removed ledger export them once to <daemon>/reports/retired-reintegration-ledger-<timestamp>.json and drop the tables at startup.

Emergency HTTPS land: caco agent land-https

The validation gate bypasses in the reintegration policy skip validation; caco agent land-https instead bypasses a wedged transport. It is an operator/controller-only emergency lever for when the daemon's canonical SSH fetch/push to the forge is wedged (the class, e.g. host egress/socket exhaustion stalling the SSH remote) while GitHub itself is healthy. It lands the agent branch over the gh HTTPS credential path, independent of the SSH canonical remote: HTTPS fetch + rebase + push, then gh pr create followed by gh pr merge --admin.

AGENT_ID="agent-id"; caco agent land-https --id "$AGENT_ID" --target main

--target defaults to main. This is not a routine land — it skips the normal SSH publish-or-refuse path — so the GitHub merge API is the freshness backstop: the branch lands through GitHub's own merge, which refuses a non-mergeable branch. Use it only when the SSH canonical remote is genuinely wedged (the Reading a static main note in the reintegration policy distinguishes a real transport freeze from a merely quiet main), and return to the normal caco agent reintegrate path once the SSH remote recovers.

Every invocation emits a dedicated reintegration_emergency_https_land audit event (queryable through caco event log) on both success (outcome="landed", carrying the resolved https_url and pr_url) and refusal (outcome="refused", carrying the error detail). The emergency land is separately git/PR-auditable too: it creates a real PR plus admin-squash-merge commit on GitHub.

Audited self-owned GitHub recovery

caco github recovery is a daemon-authorized capability surface, not a raw Git/GitHub escape hatch. It exposes exactly three generated CLI/API/MCP operations: owned-pr-branch-update, owned-ci-retrigger, and own-direct-reintegration.

Every operation requires an authenticated managed caller carrying github_recovery, exact self-ownership, and a non-empty reason. Broad worker/controller scope, cross_owner_reintegration, and every other capability are insufficient.

PR branch recovery binds the open PR, provider repository, base OID, branch, old remote head, and replacement HEAD to a clean preserved caller-owned managed/adopted checkout. It refuses default/shared/provider branches and all owner, dirt, lease, base/head, or provider drift; it performs at most one explicit force-with-lease push and reconciles an indeterminate transport result only after exact remote and PR post-reads.

Only the validated single-ref branch update receives daemon lifecycle push context, allowing the owner's -pr or -pr-g<expected-head> publication branch without relaxing the ad-hoc pre-push hook. Failed pushes retain a bounded, redacted diagnostic category in publication_evidence.push_failure; lifecycle context does not bypass the exact remote lease or provider branch protection.

This high-risk exact-identity recovery is deliberately a generated CLI/API/MCP surface rather than a TUI, web, or Android mutation control; presentation surfaces may display its redacted receipt but must not synthesize leases or reviewed Git identities.

Owned-PR repair validation requires a successful first-party job bound to the exact project, authenticated requester, canonical checkout and immutable replacement head. Binding refusals retain recovery_validation_job_mismatch or recovery_validation_checkout_unavailable and add bounded validation_binding evidence to the CLI message and redacted audit receipt. For an owner-bound job, that evidence names the differing fields and their expected/observed values after ordinary secret redaction and truncation; these affect only presentation, never the comparisons. Foreign project/requester bindings expose no observed values, terminal job status, checkout probe or head comparison. Canonical path aliases and same-node legacy requester compatibility retain their existing rules; missing or unavailable evidence never authorizes validation or publication replay.

CI recovery binds one failed/cancelled run and unambiguous workflow/check identity to that same PR head, creates at most one rerun attempt per exact request, and verifies the attempt without writing check status, skipping required CI, selecting another head, or rerunning unrelated runs.

Its write-ahead receipt records the prior attempt and selected job before dispatch; ci_evidence separates possible dispatch from the exact observed replacement attempt. Provider errors, lost responses, and post-attempt audit or transfer-commit failures remain verification_pending, never refused_no_mutation; verified attempt evidence and transfer reservations are retained. Exact replay reconciles without another rerun, including when the replacement has already failed, and reads the durable audit ledger rather than trusting a potentially stale SQLite index. A successful recovery receipt proves rerun acceptance, not passing CI; retrying a failed replacement requires a fresh request under the same authorization and identity guards.

Direct recovery requires the caller's exact durable agent, checkout, assigned bead, branch, and head, and delegates to ordinary direct cleanliness, target-freshness, validation, compare-and-verify, and true-target landed checks. Historical incident-hold records are advisory data only; explicit operator pause directives, caller authorization and protected refs remain independent.

Accepted, refused, reconciled, indeterminate, and replayed attempts append a durable redacted receipt with actor/capability, operation/reason, immutable identities, canonical-path evidence, transaction steps/fence/rollback/final attestation, result, timestamp, and secret-free request/receipt IDs. Receipt schema has no field for tokens, authorization headers, credential paths/content, PR bodies, or raw provider diagnostics.