workspace: record _call_safely extraction + seed _agent.py coverage note

Co-authored-by: Ralphify <noreply@ralphify.co>

Author: 2 people

workspace/ralphs/improve-codebase/backlog.md

@@ -8,7 +8,12 @@ only when they land in a commit.
 - Audit `_console_emitter.py` for unused private helpers / constants (grep
   each `_foo` name for other references inside the module and tests).
 - Audit `_agent.py` for parallel streaming/blocking helpers that reference
-  the same constants but define their own copies.
+  the same constants but define their own copies.  (cb61477 — extracted
+  `_call_safely` for the 3× best-effort observer-callback pattern; no
+  remaining obvious dup after that pass.  Streaming's `_readline_pump` and
+  blocking's `_pump_stream` look similar but do genuinely different work:
+  the queue-based pump feeds a main-thread loop that parses JSON, while
+  the list-based pump does its callback work inline on its own thread.)
 - Check `cli.py` validators for unreachable error branches after recent
   TypedDict refactors.
 - Confirm every `from typing import ...` import in `src/ralphify/` is used.

workspace/ralphs/improve-codebase/coverage/_agent.md

@@ -0,0 +1,55 @@
+# `_agent.py` coverage
+
+Valid at: cb61477
+
+## Recent changes
+
+- cb61477 — added `_call_safely(callback, *args)` helper next to the
+  callback type aliases.  Replaces three copies of the
+  `if cb is not None: try: cb(...); except Exception: pass` pattern
+  (two in `_read_agent_stream`, one in `_pump_stream`) with single-line
+  calls.  Behavior preserved — identical None guard, identical broad
+  `Exception` suppression, identical argument-once semantics.
+
+## Shape of the module
+
+- Two execution paths: `_run_agent_streaming` (JSON line stream, used for
+  `claude`) and `_run_agent_blocking` (subprocess.Popen with optional
+  capture, used for all other agents).
+- `execute_agent` is the single public entry point; selects mode via
+  `_supports_stream_json(cmd)` (checks `Path(cmd[0]).stem == CLAUDE_BINARY`).
+- Shared shutdown sequence is centralized in `_cleanup_agent`:
+  1. `_ensure_process_dead` (SIGTERM → SIGKILL via `_try_graceful_group_kill`,
+     then `proc.kill()`).
+  2. `_close_pipes` (raw `os.close` on stdout/stderr fds to unblock readers).
+  3. `_drain_readers` (bounded join on reader/writer threads).
+  4. `_finalize_pipes` (Python-level `pipe.close()` for GC hygiene).
+- Thread spawning uses `_start_writer_thread` / `_start_pump_thread` to
+  centralize the `Thread(..., daemon=True); .start()` boilerplate.
+
+## Verified live (grepped, confirmed used)
+
+- `CLAUDE_BINARY` — public; imported by `_console_emitter.py` for display
+  logic (see backlog note about consolidating `_is_claude_command` /
+  `_supports_stream_json`; deferred until a third caller appears).
+- `_STDOUT`, `_STDERR` — used in `_run_agent_streaming` /
+  `_run_agent_blocking` stderr pump calls and inside `_read_agent_stream`.
+- `_SIGTERM_GRACE_PERIOD`, `_THREAD_JOIN_TIMEOUT`, `_PROCESS_WAIT_TIMEOUT`
+  — each referenced exactly once; constants kept near usage as the
+  project convention prefers.
+- `AgentResult`, `_StreamResult` — returned from streaming/blocking paths
+  and consumed by `engine.py`.
+
+## Potential future wins (not yet taken)
+
+- `_run_agent_streaming` and `_run_agent_blocking` both finish with the
+  same "`stdout = "".join(...); stderr = "".join(...); log_file =
+  _write_log(...); return AgentResult(...)`" tail, but the shape of the
+  intermediate state differs (tuple vs list|None), so extracting would
+  mostly move arguments around.  Revisit only if a third execution path
+  appears.
+- The two `if proc.stdin/stdout/stderr is None: raise RuntimeError(...)`
+  guards just after `Popen` could use a single helper, but `subprocess`
+  guarantees these are non-None when `PIPE` is passed — the guards exist
+  mainly to narrow for the type checker, and a helper would make the
+  narrow less explicit.  Leave as-is.

workspace/ralphs/improve-codebase/iterations.md

@@ -2,6 +2,7 @@
 
 One line per iteration: `<sha> <summary>`.
 
+cb61477 refactor: extract `_call_safely` helper — dedupes 3× best-effort callback guards in `_agent.py`
 4ccfa9a refactor: drop redundant `if parts else ""` in `_format_params` (empty join already returns "")
 3e9627b refactor: extract `_stop_compact_live_unlocked` to dedupe compact-Live teardown across 3 call sites
 0900aad refactor: drop redundant `_iteration_order` list — dict insertion order suffices