Write terminal debug reports for failed runs

docs/internal/state.md

@@ -43,6 +43,12 @@ boundaries redact sensitive metadata and credential-shaped bytes while allowing
 application-owned trace material. Debug data is never a checkpoint source or
 cache input.
 
+After allocation, one CLI-owned state value accumulates the known report paths,
+pipeline outcome counts, and validation status. A single guarded terminalization
+operation writes the success report, or makes one attempt each to write the
+failure report and error log. Terminal persistence failures are reported
+separately and never replace the command's primary error.
+
 ## Tests To Inspect
 
 - `internal/cli/state_surfaces_test.go`: debug allocation and configuration