bot-bottle/docs/prds/0043-sidecar-pipe-lifecycle.md

PRD 0043: Sidecar Pipe Lifecycle Cleanup

• Status: Draft
• Author: didericis-codex
• Created: 2026-06-02
• Issue: #140

Summary

Close the unclosed child stdout pipe file descriptors that sidecar_init.py leaks during restart and shutdown paths, eliminating ResourceWarning noise and tightening the process lifecycle.

Problem

Unit tests for sidecar_init.py pass, but restart and shutdown cases emit ResourceWarning: unclosed file <_io.BufferedReader …> for child stdout pipes, originating around lines 141 and 273. The warnings indicate the restart path leaks pipe file descriptors: a pipe opened for a stopped or replaced child is not explicitly closed before the next child is spawned or before the supervisor exits.

Goals / Success Criteria

• python3 -m unittest tests.unit.test_sidecar_init produces no ResourceWarning output.
• Pipe file descriptors for stopped or replaced child processes are explicitly closed in the restart path.
• Pipe file descriptors for all children are explicitly closed in the shutdown path.
• No change to the external signal or exit-code contract from PRD 0034.

Non-goals

• No changes to restart or shutdown policy (coalescing, ordering, timeout).
• No changes to egress, pipelock, git-gate, or supervise daemon argv.
• No new runtime dependencies.

Scope

In scope:

• bot_bottle/sidecar_init.py pipe open/close lifecycle in _Supervisor.
• Unit tests in tests/unit/test_sidecar_init.py asserting no leaked pipes.

Out of scope:

• Changing how pumping threads read from pipes.
• Integration tests that start a live sidecar container.

Design

Audit every code path in _Supervisor where a child process is stopped, replaced, or reaches end-of-life, and ensure the corresponding stdout pipe is explicitly closed before spawning a replacement or exiting the supervisor loop.

Where a pumping thread holds a reference to the pipe, coordinate closure so the thread sees EOF and exits cleanly rather than blocking indefinitely.

Testing Strategy

• Enable ResourceWarning as an error in test setUp: warnings.simplefilter("error", ResourceWarning).
• Run existing restart and shutdown test cases under this stricter setting.
• Add tests for restart-then-shutdown if not already covered.

Run:

• python3 -m unittest tests.unit.test_sidecar_init
• python3 -m unittest discover -s tests/unit

Open Questions

None.