refactor: add explicit timed_out field to AgentResult for consistency with other result types

AgentResult was the only result type using an implicit convention (returncode
is None) to signal timeout. CheckResult, ContextResult, RunResult, and
_StreamResult all have explicit timed_out fields. This converts AgentResult
from NamedTuple to dataclass with a timed_out: bool field, making the timeout
condition self-documenting and the engine code more readable.

Also fixes stale _discover_and_filter_enabled() references in codebase-map.md
(the actual function is _discover_enabled_primitives()).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 2 people

docs/contributing/codebase-map.md

@@ -71,7 +71,7 @@ ralph run
 
 ### The three primitives and the `Primitive` protocol
 
-All three primitive types follow the same pattern: a directory under `.ralphify/` with a marker markdown file containing YAML frontmatter. Each type's dataclass (`Check`, `Context`, `Ralph`) satisfies the `Primitive` protocol defined in `_discovery.py`, which requires `name` and `enabled` properties. This enables type-safe generic functions for discovery, filtering, merging, and display — the engine's `_discover_and_filter_enabled()` helper uses the protocol to handle all three types through a single code path.
+All three primitive types follow the same pattern: a directory under `.ralphify/` with a marker markdown file containing YAML frontmatter. Each type's dataclass (`Check`, `Context`, `Ralph`) satisfies the `Primitive` protocol defined in `_discovery.py`, which requires `name` and `enabled` properties. This enables type-safe generic functions for discovery, filtering, merging, and display — the engine's `_discover_enabled_primitives()` helper uses the protocol to handle all three types through a single code path.
 
 | Primitive | Marker file | Runs | Injects into prompt |
 |---|---|---|---|
@@ -136,7 +136,7 @@ You need to:
 
 1. Create a new module (like `ralphs.py`) with a dataclass that satisfies the `Primitive` protocol (`name` and `enabled` properties), plus discover and resolve functions
 2. Add a scaffold template in `_templates.py` and a `new` subcommand in `cli.py`
-3. Wire it into `engine.py:run_loop()` — add it to `EnabledPrimitives` and use `_discover_and_filter_enabled()`
+3. Wire it into `engine.py:run_loop()` — add it to `EnabledPrimitives` and use `_discover_enabled_primitives()`
 4. Add tests
 5. Update `docs/primitives.md`
 

src/ralphify/_agent.py

@@ -20,20 +20,28 @@
 import sys
 import time
 from collections.abc import Callable
+from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import IO, NamedTuple
 
 from ralphify._output import collect_output
 
 
-class AgentResult(NamedTuple):
-    """Result of running the agent subprocess."""
+@dataclass
+class AgentResult:
+    """Result of running the agent subprocess.
 
-    returncode: int | None  # None means timed out
+    *returncode* is the process exit code, or ``None`` when the process
+    timed out.  *timed_out* makes the timeout condition explicit — prefer
+    checking ``timed_out`` over ``returncode is None``.
+    """
+
+    returncode: int | None
     elapsed: float
     log_file: Path | None
     result_text: str | None = None
+    timed_out: bool = False
 
 
 class _StreamResult(NamedTuple):
@@ -147,9 +155,11 @@ def _run_agent_streaming(
             proc.kill()
             proc.wait()
             returncode = None
+            timed_out = True
         else:
             proc.wait()
             returncode = proc.returncode
+            timed_out = False
 
         stderr_data = proc.stderr.read()
     finally:
@@ -166,6 +176,7 @@ def _run_agent_streaming(
         elapsed=time.monotonic() - start,
         log_file=log_file,
         result_text=stream.result_text,
+        timed_out=timed_out,
     )
 
 
@@ -188,6 +199,7 @@ def _run_agent_blocking(
     start = time.monotonic()
     log_file: Path | None = None
     returncode: int | None = None
+    timed_out = False
 
     try:
         result = subprocess.run(
@@ -205,13 +217,15 @@ def _run_agent_blocking(
                 sys.stderr.write(result.stderr)
         returncode = result.returncode
     except subprocess.TimeoutExpired as e:
+        timed_out = True
         if log_path_dir:
             log_file = _write_log(log_path_dir, iteration, e.stdout, e.stderr)
 
     return AgentResult(
         returncode=returncode,
         elapsed=time.monotonic() - start,
         log_file=log_file,
+        timed_out=timed_out,
     )
 
 

src/ralphify/_events.py

@@ -66,7 +66,7 @@ class EventType(Enum):
     ITERATION_COMPLETED = "iteration_completed"
     # Data: same as ITERATION_COMPLETED
     ITERATION_FAILED = "iteration_failed"
-    # Data: same as ITERATION_COMPLETED (returncode is None)
+    # Data: same as ITERATION_COMPLETED (returncode is None, timed_out is True)
     ITERATION_TIMED_OUT = "iteration_timed_out"
 
     # ── Checks ──────────────────────────────────────────────────

src/ralphify/engine.py

@@ -184,7 +184,7 @@ def _run_agent_phase(
 
     duration = format_duration(agent.elapsed)
 
-    if agent.returncode is None:
+    if agent.timed_out:
         state.mark_timed_out()
         event_type = EventType.ITERATION_TIMED_OUT
         state_detail = f"timed out after {duration}"