fix(housekeeping): bound API stalls and expose cleanup progress
Closes #526 (closed). Restores reliable diagnosis for the connected housekeeping prerequisite of !680 (merged) / #504 (closed).
Plan
- Bound API connection/read inactivity and expose safe unbuffered phase/request/result receipts.
- Stop on incomplete or timed-out reads and ambiguous writes without retrying mutations or starting later cleanup; retain settings readback and every existing retention gate.
- Execute regression/refusal tests, the actual connected settings/cleanup fixture, complete source CI and applicable owned cleanup before guarded review.
Implementation and local validation
The embedded Python is unbuffered; each API begin/result receipt is explicitly flushed. Every API connection and stalled read uses a 30-second inactivity timeout. A transport failure stops without replay or later cleanup, and transport diagnostics omit private exception details. Timed-out writes remain ambiguous and require state inspection before a manual rerun.
All 32 actual embedded-script cases pass, including the 26 existing settings/retention controls, finite timeout propagation, body-read timeout, incomplete pagination, sanitized transport errors, no mutation replay and progress-before-call. The preceding template fails the new controls. Fatal Python lint, rendered guidance and exact-source compilation pass.
No deletion limit, retention exemption, retry loop, optional failure, timeout increase or service-outage diagnosis is introduced. The preceding trace established an unbounded/buffered boundary, not a unique network or settings cause.
Acceptance / Definition of Done
- Scoped timeout/progress/no-replay behavior and representative refusal controls pass locally.
- Existing full-inventory/readback, latest/current/active/tag/child retention and non-pruning settings behavior are preserved.
- Guide explains the real inactivity timeout, partial-write boundary and state-inspection requirement; rendered page is checked.
- Actual rebuilt-image regressions and connected project settings/cleanup succeed.
- Complete latest-source CI, final diff/fresh target, all feedback and applicable owned cleanup pass.
- Nothing remains before guarded reviewer selection.
Closes #526 (closed)
Final-source evidence
Complete source CI and all three component children succeed. The rebuilt tools image executes all 32 timeout/retention/refusal cases; all 94 required shell entries pass. Actual connected housekeeping verifies settings, inventories every pipeline page, preserves all protected candidates and completes guarded environment cleanup. Both connected workflow lifecycles succeed. No review namespace or cloud deployment is created; all applicable cleanup is settled. Fresh target ancestry, identical synthetic/source trees, scoped three-file diff, rendered guide and every feedback page are checked. Ready for guarded review; no merge is claimed.