huskies: merge 645_bug_agent_runtime_panics_with_output_write_bytes_is_ok_assertion_marking_stories_falsely_blocked

server/src/agents/pty.rs

@@ -36,6 +36,22 @@ impl Drop for ChildKillerGuard {
 }
 
 /// Spawn claude agent in a PTY and stream events through the broadcast channel.
+///
+/// ## Bug 645: `output.write(&bytes).is_ok()` assertion in Claude Code CLI
+///
+/// The Claude Code CLI can panic with an `output.write(&bytes).is_ok()` assertion
+/// when writing to its stdout (the PTY slave end).  This occurs inside the child
+/// process — not in this server code — when the PTY pipe breaks or fills.  The
+/// `output` in the assertion is the CLI's stdout writer, and the write fails when
+/// the PTY master side is closed or the kernel pipe buffer is exhausted.
+///
+/// When this happens, the child process dies, the PTY reader thread in this
+/// function receives EOF, and `run_agent_pty_blocking` returns `Ok(PtyResult)`.
+/// The server then runs completion gates via `run_server_owned_completion`.
+///
+/// If the agent committed valid work before crashing, the "work survived" check
+/// in `pipeline::advance` detects the committed code and advances the story to
+/// QA instead of entering the retry/block path.
 #[allow(clippy::too_many_arguments)]
 pub(in crate::agents) async fn run_agent_pty_streaming(
     story_id: &str,