Recorded summary state artifacts

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

Recorded summary state artifacts

Recorded artifacts live under .cacophony/agent/${AGENT_ID}/.... During plain direct local reintegration, Cacophony extracts those files into the configured cacophony-state sidecar branch and strips .cacophony/agent/** from the isolated code integration tree before publishing main. Summary readers return the union of state-branch summaries and legacy default-branch summaries, de-duplicating by project, agent, and index with the state-branch copy preferred.

The legacy recorded modifier is explicit-only. During PR-backed or explicit recorded flows the code publish ref may be stripped of recorded artifacts before the push, the artifacts are published to cacophony-state, and the PR body carries a caco:summary block naming the state branch, artifact commit, and paths. Splitting derives paths from the reintegration HEAD captured at the start of the operation; the persisted agent branch name is metadata/PR context only and must not be the artifact source, because that ref can be stale. A recorded flow requested with no .cacophony/agent/... artifacts must refuse rather than open a PR without the promised durable summary. Stripping must preserve canonical checkout cleanliness: paths already tracked at HEAD are restored from HEAD after index removal and brand-new artifacts are deleted from the working tree, so neither tracked summary deletions nor untracked leftovers trip the dirty-checkout guard on unrelated reintegration.

Ordinary direct flows need not allocate the final summary index in the prompt. Agents may write a stable pending path such as .cacophony/agent/$CACO_AGENT_ID/summary/pending/summary.md; during state-branch publication the daemon assigns the final zero-padded per-agent summary/<NNNN>/ directory under the reintegration lock. Pre-numbered directories remain valid and are preserved when they do not collide with durable state; pending or colliding directories are remapped to the next index after the state-branch maximum. caco summaries next-index --agent "$CACO_AGENT_ID" remains a compatibility/preview helper for profiles that still need explicit numeric paths, but daemon-side publication is the authoritative collision-avoidance gate.

For persistent agents that build a multi-commit stack before landing, keep the pending summary as a final pre-reintegration artifact instead of editing it in each intermediate commit: store running state in caco scratch or messages, then rewrite and commit the pending summary once the content diff and validation results are known. That stops ordinary rebases from replaying stale edits against the same durable pending path.

If a direct reintegration warning leaves a local state-publication outbox, run caco summaries publish-pending [outbox-id] from the affected checkout; the optional ID narrows the retry to one bundle, and --dry-run audits multiple pending entries first. The retry fetches the latest configured state branch before pushing. If another agent advanced cacophony-state after the bundle was created, it replays the preserved sidecar commit on top of the latest tip, remaps colliding per-agent summary index directories to the next available index when that is the only conflict shape, and pushes that linearized commit. Non-summary or otherwise unmergeable state-path conflicts leave the outbox pending/failed and report the conflicting recovery scope instead of requiring manual ref reset or force-push. Dry-run and JSON output carry runtime-drift diagnostics: if the running caco binary commit differs from the checkout HEAD, publish-pending still uses the binary implementation, not unbuilt source, so update/restart caco before concluding a landed replay fix regressed.

On daemon paths that serve summaries interactively, Cacophony may keep a warmed read-only checkout of the configured cacophony-state branch under $CACOPHONY_DIR/state-branches/<project>/. Summary list/show/raw APIs prefer that cache so CLI/TUI/web/Android viewers page recorded history without fetching the remote state branch on every request, falling back to the canonical project checkout's remote-tracking ref when the cache is absent.