phase-loop-runtime 0.7.3__tar.gz → 0.7.4__tar.gz

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.3
+Version: 0.7.4
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "phase-loop-runtime"  # PyPI dist name; NOT "agent-harness" (an unrelated third-party PyPI project)
-version = "0.7.3"
+version = "0.7.4"
 description = "Harness-neutral phase-loop orchestration runtime and CLI"
 readme = "README.md"
 requires-python = ">=3.10"

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/__init__.py

@@ -18,4 +18,4 @@ __all__ = [
     "state_ops",
 ]
 
-__version__ = "0.7.3"
+__version__ = "0.7.4"

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/panel_invoker.py

@@ -1235,6 +1235,91 @@ def _run_leg_with_liveness(
                 pass
 
 
+# #188 — de-animation of the Claude TUI's cosmetic status line. While the model
+# call is in flight the TUI repaints an animated "✻ Herding… (Ns · esc to
+# interrupt)" line ~1x/sec (rotating whimsical verb + a per-second elapsed
+# counter). Those repaints are PTY output but NOT reviewer progress: a leg wedged
+# in ``ep_poll`` waiting on a stream that never completes keeps animating that
+# line forever. Treating any PTY byte as a heartbeat (the pre-#188 behavior) let
+# a wedged Fable leg hang ~17 min with ~2s CPU and no output. So for the TUI path
+# the kill clock is reset ONLY by GENUINE reviewer progress — output-file growth,
+# transcript growth, or SUBSTANTIVE novel de-animated terminal text — never by raw
+# PTY churn and never by incidental CPU (a Node CLI trickles libuv/GC CPU while
+# blocked, which would defeat a CPU heartbeat here just as the animation defeats a
+# byte heartbeat). This is exactly #188's "separate process-alive from
+# reviewer-heartbeat freshness"; the codex/grok/gemini ``_run_leg_with_liveness``
+# path keeps its stdout/stderr + CPU heartbeat (load-bearing there) untouched.
+_ANSI_CSI_RE = re.compile(r"\x1b\[[0-9;?]*[ -/]*[@-~]")
+_ANSI_OSC_RE = re.compile(r"\x1b\][^\x07\x1b]*(?:\x07|\x1b\\)")
+_TUI_DIGIT_RUN_RE = re.compile(r"\d+")
+_TUI_NON_TOKEN_RE = re.compile(r"[^0-9a-zA-Z#]+")
+# A normalized visible line must be at least this long to count as substantive
+# novelty — filters out short glyph/one-word blips while any real review sentence
+# (or streamed token run) clears it easily.
+_TUI_PROGRESS_MIN_CHARS = 8
+
+
+def _normalize_tui_line(line: str) -> str:
+    """Collapse a rendered terminal line to a spinner/timer-invariant token string.
+
+    Digit runs → ``#`` (kills the per-second elapsed counter) and every non-alnum
+    glyph/punctuation is dropped (kills the rotating spinner glyph + box drawing),
+    so the animated status line maps to a FINITE set of normalized strings while
+    genuinely-streamed review text keeps introducing novel ones.
+    """
+    line = _TUI_DIGIT_RUN_RE.sub("#", line)
+    line = _TUI_NON_TOKEN_RE.sub(" ", line)
+    return " ".join(line.split()).strip().lower()
+
+
+def _tui_chunk_has_novel_content(chunk: bytes, seen: set[str]) -> bool:
+    """True iff a PTY chunk carries SUBSTANTIVE new (non-cosmetic) terminal text.
+
+    Strips ANSI escapes, splits on newline AND carriage-return (spinner overwrite),
+    normalizes each visible line, and reports whether any sufficiently-long line
+    has not been seen before. ``seen`` accumulates for the session (bounded by real
+    novelty — a wedge's animation vocabulary is finite, so it saturates and stops
+    resetting the kill clock).
+    """
+    text = chunk.decode("utf-8", errors="replace")
+    text = _ANSI_OSC_RE.sub("", text)
+    text = _ANSI_CSI_RE.sub("", text)
+    novel = False
+    for raw in re.split(r"[\r\n]+", text):
+        norm = _normalize_tui_line(raw)
+        if len(norm) >= _TUI_PROGRESS_MIN_CHARS and norm not in seen:
+            seen.add(norm)
+            novel = True
+    return novel
+
+
+# A single ``os.read(8192)`` can split a novel review line across two chunks; each
+# fragment normalizes differently (or collides with a seen/too-short form), so the
+# whole-line progress signal is lost. Carry the trailing PARTIAL line (bytes after
+# the last newline/CR) forward and prepend it to the next chunk, so novelty is only
+# ever evaluated on COMPLETE lines. Bounded so an unterminated over-long run (a rare
+# no-newline stream) is flushed rather than growing the buffer without limit.
+_TUI_CARRY_MAX_BYTES = 1 << 16  # 64 KiB
+
+
+def _tui_take_complete_lines(carry: bytearray, chunk: bytes) -> bytes:
+    """Append ``chunk`` to ``carry`` and return the bytes up to the last line
+    terminator (complete lines, safe to scan for novelty), retaining the trailing
+    partial line in ``carry`` for the next read. Carried at the RAW byte level so a
+    straddling ANSI escape (never containing \\n/\\r) also reassembles intact."""
+    carry.extend(chunk)
+    last = max(carry.rfind(b"\n"), carry.rfind(b"\r"))
+    if last < 0:
+        if len(carry) >= _TUI_CARRY_MAX_BYTES:
+            complete = bytes(carry)
+            carry.clear()
+            return complete
+        return b""
+    complete = bytes(carry[: last + 1])
+    del carry[: last + 1]
+    return complete
+
+
 def _run_claude_tui_session(
     *,
     command: Sequence[str],
@@ -1266,8 +1351,14 @@ def _run_claude_tui_session(
     next_transcript_check = start_monotonic + _CLAUDE_TUI_TRANSCRIPT_INTERVAL_S
     transcript_salvage = ""
     last_heartbeat = start_monotonic
-    last_cpu_sample = start_monotonic
-    last_ticks = 0
+    # #188: GENUINE-progress heartbeat state. The kill clock (``last_heartbeat``)
+    # is reset ONLY by reviewer progress — never by cosmetic PTY animation or
+    # incidental CPU. ``seen_tui_lines`` accumulates de-animated visible lines so a
+    # wedged TUI's finite animation vocabulary saturates and stops resetting it.
+    seen_tui_lines: set[str] = set()
+    tui_carry = bytearray()  # #188 CR: trailing partial line held across os.read boundaries
+    last_review_len = 0
+    last_transcript_len = 0
     try:
         master_fd, slave_fd = pty.openpty()
         try:
@@ -1293,7 +1384,6 @@ def _run_claude_tui_session(
             os.close(master_fd)
         return 1, "", f"claude_tui_launch_error:{type(exc).__name__}"
 
-    last_ticks = group_cpu_ticks(proc.pid)
     try:
         while time.monotonic() < deadline:
             if master_fd is not None:
@@ -1305,7 +1395,17 @@ def _run_claude_tui_session(
                         chunk = b""
                     if chunk:
                         terminal_bytes.extend(chunk)
-                        last_heartbeat = time.monotonic()  # PTY output = liveness
+                        # #188: a raw PTY chunk is a heartbeat ONLY if it carries
+                        # SUBSTANTIVE novel text. The TUI's animated "thinking"
+                        # status line (rotating verb + per-second timer) repaints
+                        # forever while wedged in ep_poll; de-animation maps it to
+                        # already-seen lines so it never resets the kill clock.
+                        # #188 CR: carry the trailing partial line across read
+                        # boundaries so a novel line split by ``os.read`` is scanned
+                        # WHOLE (only complete lines are evaluated).
+                        complete = _tui_take_complete_lines(tui_carry, chunk)
+                        if complete and _tui_chunk_has_novel_content(complete, seen_tui_lines):
+                            last_heartbeat = time.monotonic()
                     else:
                         # #48: PTY EOF — the child CLI and ALL its descendants closed
                         # the slave side, so no further output can arrive. Without this
@@ -1341,11 +1441,20 @@ def _run_claude_tui_session(
                 except OSError:
                     return 1, "", "claude_tui_submit_failed"
             review_text = _read_review_output(output_file)
+            # #188: canonical review OUTPUT growing is unambiguous reviewer progress.
+            if len(review_text) > last_review_len:
+                last_review_len = len(review_text)
+                last_heartbeat = now
             if _completion_ok(review_text, mode):
                 return 0, review_text, "claude_tui_file_output"
             if now >= next_transcript_check:
                 next_transcript_check = now + _CLAUDE_TUI_TRANSCRIPT_INTERVAL_S
                 transcript_text = _latest_claude_transcript_text(str(cwd), since=start_wall)
+                # #188: the session transcript growing (tool calls, streamed
+                # messages) is genuine progress even before a file verdict lands.
+                if len(transcript_text) > last_transcript_len:
+                    last_transcript_len = len(transcript_text)
+                    last_heartbeat = now
                 if _completion_ok(transcript_text, mode):
                     transcript_salvage = transcript_text
             if proc.poll() is not None:
@@ -1355,14 +1464,13 @@ def _run_claude_tui_session(
                     return 0, review_text, "claude_tui_file_output"
                 detail = "claude_tui_missing_canonical_output"
                 return proc.returncode or 1, review_text or transcript_text, detail
-            # secondary CPU heartbeat (never a kill; only extends life) + stall reclaim.
-            if now - last_cpu_sample >= _LEG_LIVENESS_CPU_SAMPLE_S:
-                last_cpu_sample = now
-                ticks = group_cpu_ticks(proc.pid)
-                if ticks > last_ticks:
-                    last_heartbeat = now
-                last_ticks = ticks
-            # stall: PTY silent AND CPU-flat past the threshold while still running. The
+            # #188: NO CPU heartbeat on the TUI path. Unlike the print-mode legs, a
+            # Node CLI blocked in ep_poll still trickles libuv/GC CPU, so a CPU-advance
+            # reset would keep a genuinely-wedged TUI alive forever (the ~2s-CPU/17-min
+            # hang). Liveness here is reviewer progress ONLY (novel PTY text / output /
+            # transcript growth above) — "process-alive" is deliberately NOT "leg-alive".
+            #
+            # stall: no GENUINE progress for the threshold while still running. The
             # canonical verdict is the review FILE (checked above); nothing to nudge for a
             # wedged TUI, so fail closed (rc forced non-zero, like the #48/deadline paths).
             if now - last_heartbeat >= _LEG_STALL_THRESHOLD_S:
@@ -1729,7 +1837,15 @@ def _exec_claude_tui_leg(
         mode=mode,
         backstop_s=backstop_s,
     )
-    return _classify_leg(rc, review_text, log_text, mode), review_text or log_text
+    # #188: a heartbeat-reclaimed (genuinely wedged) TUI leg is a TYPED stalled leg,
+    # not a bare ERROR — surface it as DEGRADED so the panel summary names the
+    # liveness reclaim ("process alive but no reviewer heartbeat") while the three
+    # completed seats are preserved. A leg that produced a conforming verdict before
+    # the reclaim still classifies OK (unchanged).
+    status = _classify_leg(rc, review_text, log_text, mode)
+    if log_text == "claude_tui_stalled" and status != "OK":
+        return "DEGRADED", review_text or "claude_tui_stalled: no reviewer heartbeat (liveness reclaim)"
+    return status, review_text or log_text
 
 
 def _exec_claude_agent_view_attempt(

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime/train_roadmap.py

@@ -128,14 +128,25 @@ _NONE_VALUES = frozenset({"(none)", "none", ""})
 
 def _parse_node_id(raw: str) -> TrainNode:
     """Parse ``<repo> / <roadmap>`` or ``<repo>/<roadmap>`` into a TrainNode."""
-    raw = raw.strip()
-    if " / " in raw:
-        repo, roadmap = raw.split(" / ", 1)
-    elif "/" in raw:
-        repo, roadmap = raw.split("/", 1)
+    original = raw.strip()
+    if " / " in original:
+        repo, roadmap = original.split(" / ", 1)
+    elif "/" in original:
+        repo, roadmap = original.split("/", 1)
     else:
-        raise ValueError(f"invalid node identifier (expected '<repo> / <roadmap>'): {raw!r}")
-    return TrainNode(repo=repo.strip(), roadmap=roadmap.strip())
+        raise ValueError(f"invalid node identifier (expected '<repo> / <plan-path>'): {original!r}")
+    repo, roadmap = repo.strip(), roadmap.strip()
+    # Both components are load-bearing: `repo` selects the workspace and
+    # `roadmap` is joined onto it as the plan path. An empty half parses into a
+    # degenerate node that only fails later at child-launch (workspace / '' =
+    # the workspace dir itself). Reject it at parse time, naming the heading.
+    if not repo or not roadmap:
+        raise ValueError(
+            f"invalid node heading '### Node: {original}': both a repo and a "
+            f"plan-path are required in '<repo> / <plan-path>' form "
+            f"(got repo={repo!r}, plan-path={roadmap!r})"
+        )
+    return TrainNode(repo=repo, roadmap=roadmap)
 
 
 def _extract_node_bodies(text: str) -> List[Tuple[str, str]]:
@@ -206,7 +217,18 @@ def parse_train_roadmap(text: str) -> TrainRoadmap:
             raise ValueError(
                 f"node '{downstream.node_id}' depends on unknown node '{dep_id}'"
             )
-        channel = parse_channel_line(channel_raw)
+        # Name the offending node when the channel descriptor is malformed.
+        # parse_channel_line raises a bare "pin channel requires a 'file' param"
+        # style error; without this wrapper a train author with N nodes cannot
+        # tell WHICH node's **Channel:** line is broken (the opaque
+        # roadmap-format-handling symptom of agent-harness#60).
+        try:
+            channel = parse_channel_line(channel_raw)
+        except ValueError as exc:
+            raise ValueError(
+                f"node '{downstream.node_id}' has a malformed **Channel:** "
+                f"descriptor ({channel_raw!r}): {exc}"
+            ) from exc
         edges.append(TrainEdge(upstream=upstream, downstream=downstream, channel=channel))
 
     return TrainRoadmap(title=title, nodes=nodes, edges=edges)
@@ -233,6 +255,9 @@ def validate_train(roadmap: TrainRoadmap) -> List[str]:
           implemented for real consumption and are rejected here so that a
           train with a workspace edge fails the preflight gate — opening zero
           PRs — rather than running until injection fails mid-train.
+    (T-F) Node identifiers are unique within the train.  A duplicated
+          ``### Node:`` block would otherwise collapse in the topo-sort
+          indegree map and mis-surface as a spurious (T-D) cycle.
     """
     errors: List[str] = []
 
@@ -287,6 +312,27 @@ def validate_train(roadmap: TrainRoadmap) -> List[str]:
                 f"'workspace' channels are rejected at preflight to prevent hollow injection."
             )
 
+    # (T-F) Node identifiers must be unique within the train (authoring guide:
+    # "Node identifiers must be unique within the train"). A duplicated
+    # `### Node:` block otherwise collapses in the topo-sort indegree map and
+    # surfaces as a misleading "(T-D) cycle detected ... unresolved nodes: "
+    # with an EMPTY node list. Report it as its own coded, node-named error;
+    # the `if not errors` guard on the T-D block below then suppresses the
+    # spurious cycle. A duplicate is also a dispatch/ledger-integrity hazard:
+    # two nodes with the same id collide on the coordinator ledger key.
+    seen_ids: set = set()
+    reported_dups: set = set()
+    for node in roadmap.nodes:
+        nid = node.node_id
+        if nid in seen_ids and nid not in reported_dups:
+            errors.append(
+                f"(T-F) node id '{nid}' is declared more than once; each "
+                f"'### Node: <repo> / <plan-path>' block must be unique within "
+                f"the train (authoring guide: node identifiers must be unique)"
+            )
+            reported_dups.add(nid)
+        seen_ids.add(nid)
+
     # (T-D) Acyclic + serially orderable
     if not errors:
         try:

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: phase-loop-runtime
-Version: 0.7.3
+Version: 0.7.4
 Summary: Harness-neutral phase-loop orchestration runtime and CLI
 Author: ViperJuice
 License-Expression: Apache-2.0

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/src/phase_loop_runtime.egg-info/SOURCES.txt

@@ -512,6 +512,7 @@ tests/test_panel_native_fill_183.py
 tests/test_panel_per_leg_model_66.py
 tests/test_panel_streaming_verdicts.py
 tests/test_panel_tui_eof_48.py
+tests/test_panel_tui_liveness_188.py
 tests/test_panel_verdict_summary.py
 tests/test_parallel_dispatch_backcompat.py
 tests/test_parallel_dispatch_cli.py

phase_loop_runtime-0.7.4/tests/test_panel_tui_liveness_188.py

@@ -0,0 +1,191 @@
+"""#188 — the Claude TUI (PTY) advisor leg must be reclaimed on reviewer-heartbeat
+extinction, NOT hang on cosmetic animation and NOT rely on a fixed short timeout.
+
+Regression: after ViperJuice/agent-harness#185 the Fable panel leg runs headless
+through a self-allocated PTY (``_run_claude_tui_session`` → ``pty.openpty``). The
+pre-#188 monitor reset its stall clock on ANY PTY byte and on ANY CPU advance. But
+the Claude TUI repaints an animated "✻ Herding… (Ns · esc to interrupt)" status
+line ~1x/sec while blocked in ``ep_poll``, and a Node CLI trickles libuv/GC CPU
+while blocked — so a genuinely-wedged leg (no output, ~2s CPU) hung ~17 min and no
+timeout fired. #188 makes liveness reviewer-progress-based: cosmetic repaints and
+incidental CPU no longer count; genuine novel output / file / transcript growth do.
+
+These are real-subprocess PTY tests (like ``test_panel_tui_eof_48``): no mocking of
+the read loop, only a monkeypatched-short stall window so the wedge is caught in
+seconds instead of the production 180s.
+"""
+
+from __future__ import annotations
+
+import shutil
+import time
+
+import pytest
+
+import phase_loop_runtime.panel_invoker as pi
+from phase_loop_runtime.panel_invoker import _classify_leg, _run_claude_tui_session
+
+pytestmark = pytest.mark.skipif(shutil.which("sh") is None, reason="needs POSIX sh")
+
+# A hermetic empty transcript: tmp cwds have no ~/.claude project, but pin it so the
+# transcript-growth heartbeat can never spuriously reset the clock in these tests.
+_NO_TRANSCRIPT = lambda *a, **k: ""  # noqa: E731
+
+
+# A wedged TUI: repaints the SAME animated status line each ~0.1s (only the elapsed
+# digit changes → de-animates to a single seen line), burns a CPU trickle each
+# iteration, never writes the review file, never exits. This is the "~2s CPU / no
+# output / animating forever" signature of the #188 repro.
+_WEDGE_SCRIPT = (
+    "i=0; while :; do "
+    "  i=$((i+1)); "
+    "  s=0; while [ $s -lt 3000 ]; do s=$((s+1)); done; "  # CPU trickle
+    r'  printf "\r\033[2K* Herding... (%ss . esc to interrupt)" "$i"; '
+    "  sleep 0.1; "
+    "done"
+)
+
+# A slow-but-progressing TUI: emits a NOVEL de-animated line each ~0.6s (distinct
+# words, not just a changing digit) with NO file output, then exits. Each novel line
+# is a genuine reviewer heartbeat; the leg must survive many stall windows.
+_PROGRESS_SCRIPT = (
+    "for w in alpha bravo charlie delta echo foxtrot golf hotel india juliet; do "
+    r'  printf "reviewing the %s section of the staged bundle now\n" "$w"; '
+    "  sleep 0.6; "
+    "done"
+)
+
+
+def test_wedged_pty_leg_is_reclaimed_on_heartbeat_extinction(tmp_path, monkeypatch):
+    """(a) A silent-hung PTY leg that keeps ANIMATING (cosmetic repaints) and trickles
+    CPU is detected and terminated within the stall window — NOT at the wall-clock
+    backstop, NOT never. The generous backstop (120s) proves the kill is heartbeat
+    reclaim, not a fixed timeout."""
+    monkeypatch.setattr(pi, "_LEG_STALL_THRESHOLD_S", 3)
+    monkeypatch.setattr(pi, "_CLAUDE_TUI_SUBMIT_DELAY_S", 999)  # never submit; irrelevant here
+    monkeypatch.setattr(pi, "_latest_claude_transcript_text", _NO_TRANSCRIPT)
+    output_file = tmp_path / "panel-claude.txt"  # never written
+
+    start = time.monotonic()
+    rc, text, status = _run_claude_tui_session(
+        command=["sh", "-c", _WEDGE_SCRIPT],
+        cwd=tmp_path,
+        prompt="review this",
+        output_file=output_file,
+        timeout_s=120,
+        env={"PATH": "/usr/bin:/bin"},
+        backstop_s=120,  # generous: a fixed-timeout kill would need this to be short
+    )
+    elapsed = time.monotonic() - start
+
+    assert status == "claude_tui_stalled", (
+        f"wedged animating TUI must be reclaimed as stalled; got {status!r} "
+        f"(pre-#188: cosmetic repaints reset the heartbeat forever)"
+    )
+    assert 3 <= elapsed < 30, (
+        f"reclaim took {elapsed:.1f}s — must be ~stall_threshold (3s), not the 120s "
+        f"backstop (would prove a fixed timeout) and not never"
+    )
+    assert rc != 0, f"a reclaimed wedge must be fail-closed non-zero; got rc={rc}"
+
+
+def test_wedged_stall_marker_classifies_degraded(tmp_path, monkeypatch):
+    """(a cont.) The reclaimed stall is surfaced as a TYPED leg. ``_exec_claude_tui_leg``
+    maps the ``claude_tui_stalled`` marker to DEGRADED (never a silent OK / bare ERROR),
+    so the panel summary names the reclaim while the completed seats are preserved. This
+    exercises the REAL wiring (not a re-implementation of the mapping)."""
+    review_dir = tmp_path / "review"
+    out_dir = tmp_path / "out"
+    review_dir.mkdir()
+    out_dir.mkdir()
+    # Run the leg RIGHT HERE (headless self-PTY path): not under Claude Code, CLI supported.
+    monkeypatch.setattr(pi, "_under_claude_code", lambda env=None: False)
+    monkeypatch.setattr(pi, "_claude_code_support_status", lambda: (True, ""))
+    monkeypatch.setattr(pi, "_subscription_env", lambda: {"PATH": "/usr/bin:/bin"})
+    # The session reclaims a genuinely-wedged leg: non-zero rc, no verdict, stall marker.
+    monkeypatch.setattr(pi, "_run_claude_tui_session", lambda **kwargs: (1, "", "claude_tui_stalled"))
+
+    status, _text = pi._exec_claude_tui_leg(review_dir, out_dir, 120, "bundle")
+
+    assert status == "DEGRADED", (
+        f"a heartbeat-reclaimed wedge must be surfaced as DEGRADED (typed stalled leg), "
+        f"not a bare ERROR/silent OK; got {status!r}"
+    )
+    assert status in pi.LEG_STATUSES
+
+
+def test_slow_but_progressing_pty_leg_is_not_killed(tmp_path, monkeypatch):
+    """(b) A leg that emits NOVEL de-animated terminal text every interval (genuine
+    reviewer heartbeat) survives many stall windows and is NOT false-killed — even with
+    no file output yet and the same short stall threshold that reclaims the wedge."""
+    monkeypatch.setattr(pi, "_LEG_STALL_THRESHOLD_S", 2)
+    monkeypatch.setattr(pi, "_CLAUDE_TUI_SUBMIT_DELAY_S", 999)  # isolate the PTY-progress signal
+    monkeypatch.setattr(pi, "_latest_claude_transcript_text", _NO_TRANSCRIPT)
+    output_file = tmp_path / "panel-claude.txt"  # intentionally never written by the script
+
+    start = time.monotonic()
+    rc, text, status = _run_claude_tui_session(
+        command=["sh", "-c", _PROGRESS_SCRIPT],
+        cwd=tmp_path,
+        prompt="review this",
+        output_file=output_file,
+        timeout_s=120,
+        env={"PATH": "/usr/bin:/bin"},
+        backstop_s=120,
+    )
+    elapsed = time.monotonic() - start
+
+    assert status != "claude_tui_stalled", (
+        f"a leg emitting novel output every 0.6s must NOT be reclaimed as stalled "
+        f"(stall window was 2s); got {status!r} after {elapsed:.1f}s"
+    )
+    # 10 novel lines × 0.6s ≈ 6s, far past 2× the 2s stall window — proof it lived on
+    # its reviewer heartbeat, then exited on its own (no canonical file → typed miss).
+    assert elapsed > 4, f"leg exited/was reclaimed too early ({elapsed:.1f}s) — progress heartbeat failed"
+    # It lived on its reviewer heartbeat and then ended on ITS OWN terms (the script
+    # exits and closes the PTY → structured EOF / missing-canonical result), never a
+    # liveness reclaim. The exact terminal detail depends on exit-vs-poll ordering.
+    assert status in {"claude_tui_pty_eof_no_output", "claude_tui_missing_canonical_output"}, status
+
+
+def test_novel_line_split_across_read_boundaries_is_detected_whole():
+    """(b cont., #188 CR) A novel review line delivered in TWO halves across two
+    ``os.read`` boundaries must register as ONE progress event once the line completes
+    — the carry-buffer holds the trailing partial line so novelty is evaluated on the
+    WHOLE line, not on fragments (which could each collide with a seen/too-short form
+    and silently drop the heartbeat)."""
+    seen: set[str] = set()
+    carry = bytearray()
+
+    # First read delivers the line WITHOUT a terminator: no complete line yet, so
+    # nothing is evaluated and no fragment pollutes `seen`.
+    complete1 = pi._tui_take_complete_lines(carry, b"reviewing the acceptance crit")
+    assert complete1 == b"", "an unterminated partial line must not be emitted"
+    assert not pi._tui_chunk_has_novel_content(complete1, seen)
+    assert seen == set(), "no fragment should be recorded before the line completes"
+
+    # Second read completes the line (adds the tail + newline): now the WHOLE line is
+    # evaluated and counts as novel progress.
+    complete2 = pi._tui_take_complete_lines(carry, b"eria section now\n")
+    assert pi._tui_chunk_has_novel_content(complete2, seen), (
+        "the reassembled whole line must be detected as novel progress"
+    )
+    # The recorded token is the whole normalized line, not either half.
+    assert "reviewing the acceptance criteria section now" in seen
+    assert carry == bytearray(), "no residue after a terminated line"
+
+
+def test_no_fixed_short_timeout_is_injected_when_caller_did_not_request_one(tmp_path):
+    """(c) With no caller-supplied per-leg timeout, the runtime does NOT inject a fixed
+    model timeout: the hard deadline is raised to the _MAX backstop and the real kill is
+    heartbeat reclaim (tested above). An explicit override is still honored as-is."""
+    (tmp_path / "review-bundle.md").write_text("small bundle", encoding="utf-8")
+
+    ref_default, deadline_default = pi._leg_deadline_from(None, tmp_path)
+    # No fixed short timeout: the backstop is the generous _MAX (>= 1800s), not the base.
+    assert deadline_default >= pi._MAX_LEG_TIMEOUT_S
+    assert deadline_default > pi._LEG_TIMEOUT_BASE_S
+
+    # An EXPLICIT caller override is honored verbatim (still bounded — the contract path).
+    ref_explicit, deadline_explicit = pi._leg_deadline_from(300, tmp_path)
+    assert (ref_explicit, deadline_explicit) == (300, 300)

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/tests/test_train_invariants.py

@@ -1296,3 +1296,49 @@ class TestInvariant7RunLoopFailureContract:
             "_pipeline_branch_blocker_from_error each contribute one).  "
             "A removed default would let a failure path silently emit None."
         )
+
+
+# ---------------------------------------------------------------------------
+# agent-harness#60 (roadmap-format-handling half): a format defect that survives
+# parse (a duplicated node block) must be caught by run_train's Step-0 schema
+# gate as preflight_failed with ZERO publish calls and an actionable, node-named
+# diagnostic — binding the format fix to INV-3's zero-PR contract.
+
+TRAIN_DUP_NODE_MD = TRAIN_2NODE_MD + (
+    "\n### Node: repo-a / specs/plan-a.md\n\n"
+    "**Depends on:** (none)\n**Channel:** (none)\n"
+)
+
+
+class TestIssue60FormatDefectZeroPRs:
+    def test_duplicate_node_train_preflight_failed_zero_publish(self, tmp_path: Path):
+        roadmap = parse_train_roadmap(TRAIN_DUP_NODE_MD)  # parse tolerates dup
+        ws_map = {n.node_id: tmp_path / n.repo for n in roadmap.nodes}
+        ledger = tmp_path / "ledger" / "train.ledger.jsonl"
+        publish_log: List[str] = []
+
+        def _publish_spy(workspace: Path, owned_paths, *, draft: bool, **kw):
+            publish_log.append(workspace.name)
+            return {"status": "published", "branch": "b", "head_sha": "s", "pr_url": "u"}
+
+        result = run_train(
+            roadmap,
+            ledger,
+            run_mode="governed",
+            resolve_workspace=lambda n: ws_map[n.node_id],
+            _run_loop=lambda *a, **kw: (None, []),
+            _publish=_publish_spy,
+            _set_upstream_ref_fn=lambda *a, **kw: [],
+            _preflight_fn=_preflight_pass,  # repo-preflight would pass; schema gate must fire first
+            _pr_is_open=_pr_is_open_false,
+            _live_pr_head_sha_fn=lambda ws, br: None,
+            _merge_phase_enabled=True,
+        )
+
+        assert result["status"] == "preflight_failed", result
+        assert publish_log == [], f"format defect must open zero PRs; got {publish_log!r}"
+        joined = " ".join(result["errors"])
+        assert "(T-F)" in joined and "repo-a/specs/plan-a.md" in joined, (
+            f"diagnostic must be coded and name the duplicated node; got: {result['errors']}"
+        )
+        assert not ledger.exists() or read_ledger(ledger) == {}, "no ledger records on schema failure"

{phase_loop_runtime-0.7.3 → phase_loop_runtime-0.7.4}/tests/test_train_roadmap.py

@@ -811,3 +811,82 @@ class TestUnsupportedChannelKindInTrain:
         errors = validate_train(r)
         t_e_errors = [e for e in errors if "(T-E)" in e]
         assert not t_e_errors, f"Expected no T-E errors for supported channels; got: {t_e_errors}"
+
+
+# ---------------------------------------------------------------------------
+# agent-harness#60 — roadmap-format-handling half: opaque parse/validate
+# failures on authoring-guide-shaped input must become actionable diagnostics
+# that name the offending node (and, for duplicates, avoid a false T-D cycle).
+
+
+class TestIssue60FormatHandling:
+    """Regression tests for the roadmap-format-handling half of #60.
+
+    Each previously either (a) raised a ValueError that did NOT name which node
+    was malformed, (b) was silently accepted, or (c) mis-surfaced as a spurious
+    (T-D) cycle with an empty unresolved-node list.
+    """
+
+    _GOOD = VALID_TRAIN_3NODE_MD
+
+    # --- Gap A: malformed **Channel:** descriptor must name the node ---------
+
+    def test_pin_missing_file_names_node(self) -> None:
+        bad = self._GOOD.replace(
+            "pin file=manifest.json key=deps.alpha-lib", "pin key=deps.alpha-lib"
+        )
+        with pytest.raises(ValueError) as exc:
+            parse_train_roadmap(bad)
+        msg = str(exc.value)
+        assert "beta/specs/beta.md" in msg, f"error must name the node; got: {msg}"
+        assert "Channel" in msg and "pin" in msg
+
+    def test_unknown_channel_kind_names_node(self) -> None:
+        bad = self._GOOD.replace("submodule path=vendor/beta", "submdoule path=vendor/beta")
+        with pytest.raises(ValueError) as exc:
+            parse_train_roadmap(bad)
+        msg = str(exc.value)
+        assert "gamma/specs/gamma.md" in msg, f"error must name the node; got: {msg}"
+        assert "submdoule" in msg
+
+    def test_submodule_missing_path_names_node(self) -> None:
+        bad = self._GOOD.replace("submodule path=vendor/beta", "submodule")
+        with pytest.raises(ValueError) as exc:
+            parse_train_roadmap(bad)
+        assert "gamma/specs/gamma.md" in str(exc.value)
+
+    # --- Gap B: duplicate node id → coded (T-F), NOT a spurious cycle --------
+
+    def test_duplicate_node_id_reports_t_f_not_cycle(self) -> None:
+        dup = self._GOOD + (
+            "\n### Node: alpha / specs/alpha.md\n\n"
+            "**Depends on:** (none)\n**Channel:** (none)\n"
+        )
+        r = parse_train_roadmap(dup)  # parse tolerates; validate is the gate
+        errors = validate_train(r)
+        t_f = [e for e in errors if "(T-F)" in e]
+        assert t_f, f"expected a (T-F) duplicate-node error; got: {errors}"
+        assert "alpha/specs/alpha.md" in t_f[0]
+        # The old buggy behavior mis-reported this as a (T-D) cycle with an
+        # empty unresolved-node list — assert that no longer happens.
+        assert not [e for e in errors if "(T-D)" in e], (
+            f"duplicate must NOT surface as a (T-D) cycle; got: {errors}"
+        )
+
+    def test_genuine_cycle_still_reports_t_d(self) -> None:
+        """Guard: the T-F check must not mask a real cycle of distinct nodes."""
+        r = parse_train_roadmap(CYCLIC_TRAIN_MD)
+        errors = validate_train(r)
+        assert [e for e in errors if "(T-D)" in e], f"got: {errors}"
+
+    # --- Gap C: empty repo / plan-path component rejected at parse -----------
+
+    def test_empty_plan_path_rejected(self) -> None:
+        bad = "# Release Train: t\n\n## Nodes\n\n### Node: spec /\n\n**Depends on:** (none)\n**Channel:** (none)\n"
+        with pytest.raises(ValueError, match="plan-path"):
+            parse_train_roadmap(bad)
+
+    def test_empty_repo_rejected(self) -> None:
+        bad = "# Release Train: t\n\n## Nodes\n\n### Node:  / specs/x.md\n\n**Depends on:** (none)\n**Channel:** (none)\n"
+        with pytest.raises(ValueError, match="repo"):
+            parse_train_roadmap(bad)