From 85e73e013da51a4194f55ffe7636daed82a90ae3 Mon Sep 17 00:00:00 2001
From: "didericis (claude)" <eric+claude@dideric.is>
Date: Tue, 2 Jun 2026 10:28:24 -0400
Subject: [PATCH] docs: add PRD 0043

---
 docs/prds/0043-sidecar-pipe-lifecycle.md | 74 ++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/prds/0043-sidecar-pipe-lifecycle.md

diff --git a/docs/prds/0043-sidecar-pipe-lifecycle.md b/docs/prds/0043-sidecar-pipe-lifecycle.md
new file mode 100644
index 0000000..1e34df2
--- /dev/null
+++ b/docs/prds/0043-sidecar-pipe-lifecycle.md
@@ -0,0 +1,74 @@
+# 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.