@team-agent/installer 0.2.2 → 0.2.4

package/src/team_agent/messaging/tmux_io.py

@@ -20,6 +20,7 @@ from team_agent.messaging.deps import (
 
 from pathlib import Path
 from typing import Any
+from team_agent.messaging.tmux_prompt import detect_non_input_scrollback, non_input_scrollback_window
 
 def _tmux_inject_text(
     target: str,
@@ -28,7 +29,52 @@ def _tmux_inject_text(
     buffer_name: str,
     attempts: int = 3,
     provider: str = "fake",
+    *,
+    bypass_non_input_gate: bool = False,
 ) -> dict[str, Any]:
+    # Round-5 follow-up: empty-text Enter path (used by trust auto-answer to
+    # accept Codex's default `1. Yes, continue` choice with a plain Enter).
+    # tmux rejects set-buffer / paste-buffer of an empty string, so the
+    # buffer-paste route would leave the trust prompt stuck. Issue
+    # `send-keys -t <target> <submit_key>` directly and bypass the buffer
+    # path entirely.
+    if text == "":
+        proc = run_cmd(["tmux", "send-keys", "-t", target, submit_key], timeout=10)
+        if proc.returncode != 0:
+            return {
+                "ok": False,
+                "stage": "send-keys",
+                "error": proc.stderr.strip() or "tmux send-keys failed",
+                "attempts": [
+                    {
+                        "attempt": 1,
+                        "submitted": False,
+                        "verification": "send_keys_failed",
+                        "submit_key": submit_key,
+                    }
+                ],
+                "verification": "send_keys_failed",
+            }
+        return {
+            "ok": True,
+            "stage": "submitted",
+            "visible": True,
+            "submitted": True,
+            "verification": "empty_text_send_keys",
+            "submit_verification": f"{submit_key}_sent_direct",
+            "turn_verification": "not_required",
+            "attempts": [
+                {
+                    "attempt": 1,
+                    "submitted": True,
+                    "verification": "empty_text_send_keys",
+                    "submit_key": submit_key,
+                }
+            ],
+            "submit_attempts": [
+                {"attempt": 1, "submitted": True, "verification": "send_keys"}
+            ],
+        }
     token_match = re.search(r"\[team-agent-token:([^\]]+)\]", text)
     token = token_match.group(1) if token_match else ""
     attempt_log: list[dict[str, Any]] = []
@@ -37,15 +83,25 @@ def _tmux_inject_text(
     submit_settle_timeout = _tmux_submit_settle_timeout(text)
     text_bytes = _tmux_text_size(text)
     for attempt in range(1, max(attempts, 1) + 1):
-        prepared = _prepare_tmux_pane_for_input(target)
+        prepared = (
+            {"ok": True, "verification": "non_input_gate_bypassed"}
+            if bypass_non_input_gate
+            else _prepare_tmux_pane_for_input(target)
+        )
         if not prepared["ok"]:
-            attempt_log.append({"attempt": attempt, "visible": False, "verification": prepared["verification"]})
+            attempt_log.append(_prepare_failure_attempt(attempt, prepared))
             return {
                 "ok": False,
+                "status": "failed",
                 "stage": prepared["stage"],
+                "reason": prepared.get("reason"),
                 "error": prepared.get("error"),
                 "attempts": attempt_log,
                 "verification": prepared["verification"],
+                "detected": prepared.get("detected"),
+                "pane_id": prepared.get("pane_id"),
+                "pane_mode": prepared.get("pane_mode"),
+                "pane_capture_tail": prepared.get("pane_capture_tail"),
             }
         baseline = _capture_tmux_pane_text(target)
         if not baseline["ok"]:
@@ -97,6 +153,9 @@ def _tmux_inject_text(
             attempt_entry["buffer_delete_error"] = deleted.get("error")
         if prepared.get("recovered_from_mode"):
             attempt_entry["recovered_from_mode"] = True
+            attempt_entry["recovered_from_pane_mode"] = prepared.get("pane_mode")
+        if prepared.get("warning_event"):
+            attempt_entry["warning_event"] = prepared["warning_event"]
         attempt_log.append(attempt_entry)
         if not visible:
             time.sleep(0.2)
@@ -118,6 +177,11 @@ def _tmux_inject_text(
                 "submit_attempts": submit.get("attempts"),
             }
         submit_verification = _leader_submit_verification(submit.get("verification"), verification, submit_key)
+        # Gap 42: paste+submit success is authoritative for delivery. The post-submit
+        # turn-boundary probe is observation metadata only, never a delivery gate — a
+        # busy / compacting recipient that has not yet shown a new prompt marker is
+        # still a successful delivery. Real paste/submit failures are caught and
+        # returned above; this point is only reached after submit reported ok.
         turn_visible, turn_verification, turn_capture = _wait_for_leader_new_turn(
             target,
             text,
@@ -126,16 +190,7 @@ def _tmux_inject_text(
             timeout=2.0,
         )
         if not turn_visible:
-            return {
-                "ok": False,
-                "stage": "turn-boundary-verification",
-                "error": f"leader turn boundary not verified: {turn_verification}",
-                "attempts": attempt_log,
-                "verification": verification,
-                "submit_verification": submit_verification,
-                "turn_verification": turn_verification,
-                "submit_attempts": submit.get("attempts"),
-            }
+            turn_verification = "not_yet_observed"
         return {
             "ok": True,
             "stage": "submitted",
@@ -276,50 +331,164 @@ def _tmux_load_buffer_stdin(buffer_name: str, text: str) -> subprocess.Completed
 
 
 def _prepare_tmux_pane_for_input(target: str) -> dict[str, Any]:
-    mode = run_cmd(["tmux", "display-message", "-p", "-t", target, "#{pane_in_mode}"], timeout=5)
-    if mode.returncode != 0:
+    mode_result = _pane_mode(target)
+    if not mode_result["ok"]:
         return {
             "ok": False,
             "stage": "pane-mode-check",
             "verification": "pane_mode_check_failed",
-            "error": mode.stderr.strip() or "tmux pane mode check failed",
+            "error": mode_result.get("error") or "tmux pane mode check failed",
         }
-    if mode.stdout.strip() != "1":
-        return {"ok": True, "verification": "pane_input_ready"}
-    cancel = run_cmd(["tmux", "send-keys", "-t", target, "-X", "cancel"], timeout=10)
-    if cancel.returncode != 0:
+    capture_result = _pane_capture_tail(target, lines=30)
+    if not capture_result["ok"]:
         return {
             "ok": False,
-            "stage": "pane-mode-cancel",
-            "verification": "pane_mode_cancel_failed",
-            "error": cancel.stderr.strip() or "tmux copy-mode cancel failed",
+            "stage": "pane-tail-capture",
+            "verification": "pane_tail_capture_failed",
+            "error": capture_result.get("error") or "tmux capture-pane failed",
         }
+    pane_mode = _normalize_pane_mode(mode_result.get("pane_mode"))
+    capture_tail = str(capture_result.get("capture") or "")
+    detected = detect_non_input_scrollback(capture_tail)
+    if detected:
+        return _non_input_refusal(target, pane_mode, capture_tail, detected)
+    if not pane_mode:
+        return {"ok": True, "verification": "pane_input_ready"}
+    cancel = _pane_mode_cancel(target, pane_mode)
+    if not cancel["ok"]:
+        return _non_input_refusal(
+            target,
+            pane_mode,
+            capture_tail,
+            f"tmux_{pane_mode}",
+            error=cancel.get("error") or "tmux pane mode cancel failed",
+            verification="pane_mode_cancel_failed",
+            warning_event=cancel.get("warning_event"),
+        )
+    warning_event = cancel.get("warning_event")
     deadline = time.monotonic() + 1.5
     while True:
-        check = run_cmd(["tmux", "display-message", "-p", "-t", target, "#{pane_in_mode}"], timeout=5)
-        if check.returncode != 0:
+        check = _pane_mode(target)
+        if not check["ok"]:
             return {
                 "ok": False,
                 "stage": "pane-mode-check",
                 "verification": "pane_mode_recheck_failed",
-                "error": check.stderr.strip() or "tmux pane mode recheck failed",
+                "error": check.get("error") or "tmux pane mode recheck failed",
             }
-        if check.stdout.strip() != "1":
-            return {"ok": True, "verification": "pane_input_ready_after_mode_cancel", "recovered_from_mode": True}
-        if time.monotonic() >= deadline:
-            return {
-                "ok": False,
-                "stage": "pane-mode-cancel",
-                "verification": "pane_mode_still_active_after_cancel",
-                "error": "tmux pane stayed in copy-mode after cancel",
+        if not _normalize_pane_mode(check.get("pane_mode")):
+            result = {
+                "ok": True,
+                "verification": "pane_input_ready_after_mode_cancel",
+                "recovered_from_mode": True,
+                "pane_mode": pane_mode,
             }
+            if warning_event:
+                result["warning_event"] = warning_event
+            return result
+        if time.monotonic() >= deadline:
+            return _non_input_refusal(
+                target,
+                pane_mode,
+                capture_tail,
+                f"tmux_{pane_mode}",
+                error=f"tmux pane stayed in {pane_mode} after cancel",
+                verification="pane_mode_still_active_after_cancel",
+                warning_event=warning_event,
+            )
         time.sleep(0.1)
 
 
+def _pane_mode(target: str) -> dict[str, Any]:
+    proc = run_cmd(["tmux", "display-message", "-p", "-t", target, "#{pane_mode}"], timeout=5)
+    if proc.returncode != 0:
+        return {"ok": False, "error": proc.stderr.strip() or "tmux pane mode check failed"}
+    return {"ok": True, "pane_mode": proc.stdout.strip()}
+
+
+def _pane_capture_tail(target: str, lines: int = 30) -> dict[str, Any]:
+    capture = run_cmd(["tmux", "capture-pane", "-p", "-S", f"-{lines}", "-t", target], timeout=5)
+    if capture.returncode != 0:
+        return {"ok": False, "capture": "", "error": capture.stderr.strip() or "tmux capture-pane failed"}
+    return {"ok": True, "capture": capture.stdout}
+
+
+def _pane_mode_cancel(target: str, pane_mode: str) -> dict[str, Any]:
+    mode = _normalize_pane_mode(pane_mode)
+    warning_event = None
+    if mode == "copy-mode":
+        args = ["tmux", "send-keys", "-t", target, "-X", "cancel"]
+    elif mode in {"tree-mode", "view-mode"}:
+        args = ["tmux", "send-keys", "-t", target, "q"]
+    elif mode == "client-mode":
+        args = ["tmux", "send-keys", "-t", target, "d"]
+    else:
+        args = ["tmux", "send-keys", "-t", target, "-X", "cancel"]
+        warning_event = "pane_mode_unknown_cancel_attempted"
+    cancel = run_cmd(args, timeout=10)
+    if cancel.returncode != 0:
+        return {
+            "ok": False,
+            "error": cancel.stderr.strip() or f"tmux {mode or 'unknown'} cancel failed",
+            "warning_event": warning_event,
+        }
+    result = {"ok": True, "mode": mode, "args": args}
+    if warning_event:
+        result["warning_event"] = warning_event
+    return result
+
+
+def _normalize_pane_mode(mode: Any) -> str:
+    value = str(mode or "").strip()
+    if value == "0":
+        return ""
+    if value == "1":
+        return "copy-mode"
+    return value
+
+
+def _non_input_refusal(
+    target: str,
+    pane_mode: str,
+    capture_tail: str,
+    detected: str,
+    *,
+    error: str | None = None,
+    verification: str = "recipient_pane_in_non_input_mode",
+    warning_event: str | None = None,
+) -> dict[str, Any]:
+    result = {
+        "ok": False,
+        "status": "failed",
+        "stage": "pre-paste-pane-state",
+        "reason": "recipient_pane_in_non_input_mode",
+        "error": error or "recipient_pane_in_non_input_mode",
+        "verification": verification,
+        "detected": detected,
+        "pane_id": target,
+        "pane_mode": pane_mode,
+        "pane_capture_tail": non_input_scrollback_window(capture_tail) or _last_lines(capture_tail, 10),
+    }
+    if warning_event:
+        result["warning_event"] = warning_event
+    return result
 
 
+def _prepare_failure_attempt(attempt: int, prepared: dict[str, Any]) -> dict[str, Any]:
+    entry = {
+        "attempt": attempt,
+        "visible": False,
+        "verification": prepared["verification"],
+    }
+    for key in ("reason", "detected", "pane_id", "pane_mode", "pane_capture_tail", "warning_event"):
+        if key in prepared:
+            entry[key] = prepared[key]
+    return entry
 
 
+def _last_lines(text: str, count: int) -> str:
+    lines = text.splitlines()
+    return "\n".join(lines[-count:])
 
 
 

package/src/team_agent/messaging/tmux_prompt.py

@@ -12,6 +12,93 @@ from team_agent.messaging.deps import (
 from pathlib import Path
 from typing import Any
 
+
+_ANSI_ESCAPE_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
+
+
+def detect_non_input_scrollback(capture_tail: str) -> str | None:
+    nonempty = _non_input_scrollback_lines(capture_tail)
+    tail_text = "\n".join(nonempty)
+    lower = tail_text.lower()
+    stale_before_input = _stale_non_input_before_ready_prompt(nonempty)
+    if re.search(r"do\s+you\s+trust\s+the\s+contents\s+of\s+this\s+directory", lower):
+        if stale_before_input:
+            return None
+        return "codex_trust_prompt"
+    if "press enter to log in" in lower or "press enter to login" in lower:
+        if stale_before_input:
+            return None
+        return "codex_first_run_auth"
+    if "capability may degrade" in lower:
+        if stale_before_input:
+            return None
+        return "codex_compaction_warning"
+    if re.search(r"press\s+(enter|return)\s+to\s+continue", lower):
+        if stale_before_input:
+            return None
+        return "generic_press_enter"
+    if re.search(r"press\s+any\s+key", lower):
+        if stale_before_input:
+            return None
+        return "generic_press_enter"
+    if re.search(r"(\(y/n\)|\([yY]/n\)|\[y/N\]|\[Y/n\]|\[y/n\])", tail_text):
+        if stale_before_input:
+            return None
+        return "y_n_confirm"
+    for first, second in zip(nonempty, nonempty[1:]):
+        if _starts_numbered_choice(first, "1") and _starts_numbered_choice(second, "2"):
+            if stale_before_input:
+                return None
+            return "numbered_menu"
+    if nonempty:
+        last = nonempty[-1]
+        if re.search(r"(^|[\s~/.\w-])[$%]\s*$", last):
+            return "shell_prompt_cli_dead"
+    return None
+
+
+def non_input_scrollback_window(capture_tail: str, limit: int = 15) -> str:
+    return "\n".join(_non_input_scrollback_lines(capture_tail, limit=limit))
+
+
+def _non_input_scrollback_lines(capture_tail: str, limit: int = 15) -> list[str]:
+    lines = [_ANSI_ESCAPE_RE.sub("", line).rstrip() for line in capture_tail.splitlines()]
+    while lines and not lines[-1].strip():
+        lines.pop()
+    return [line for line in lines if line.strip()][-limit:]
+
+
+def _starts_numbered_choice(line: str, number: str) -> bool:
+    return bool(re.match(rf"^\s*(?:[›❯>]\s*)?{number}\.\s+", line))
+
+
+def _stale_non_input_before_ready_prompt(lines: list[str]) -> bool:
+    latest_non_input = -1
+    latest_ready = -1
+    for index, line in enumerate(lines):
+        lower = line.lower()
+        if (
+            "do you trust the contents of this directory" in lower
+            or re.search(r"press\s+(enter|return)\s+to\s+continue", lower)
+            or re.search(r"press\s+any\s+key", lower)
+            or _starts_numbered_choice(line, "1")
+            or _starts_numbered_choice(line, "2")
+        ):
+            latest_non_input = index
+        if _is_input_ready_prompt(line):
+            latest_ready = index
+    return latest_non_input >= 0 and latest_ready > latest_non_input
+
+
+def _is_input_ready_prompt(line: str) -> bool:
+    if _starts_numbered_choice(line, "1") or _starts_numbered_choice(line, "2"):
+        return False
+    value = line.strip()
+    if re.match(r"^[›❯>]\s+\S", value):
+        return True
+    return bool(re.search(r"\b(codex|claude)\s*[>›❯]\s*$", value, re.IGNORECASE))
+
+
 def _enable_codex_fast_mode(session_name: str, window_name: str) -> dict[str, Any]:
     target = f"{session_name}:{window_name}"
     proc = run_cmd(["tmux", "send-keys", "-t", target, "/fast", "Enter"], timeout=10)

package/src/team_agent/messaging/trust_auto_answer.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from team_agent.events import EventLog
+from team_agent.messaging.deps import _tmux_inject_text
+
+
+def retry_injection_after_trust_auto_answer(
+    workspace: Path,
+    state: dict[str, Any],
+    event_log: EventLog,
+    injection: dict[str, Any],
+    target: str,
+    text: str,
+    submit_key: str,
+    buffer_name: str,
+    provider: str,
+) -> dict[str, Any]:
+    from team_agent.messaging.delivery import _tmux_pane_width, _wait_for_trust_prompt_dismissal
+    from team_agent.messaging.leader_panes import attempt_trust_auto_answer
+    pane_target = injection.get("pane_id") or target
+    # Live wiring: query tmux pane width now and pass via state["pane_width"]
+    # (symmetric with _deliver_pending_message). Fail-safe on query failure —
+    # leave pane_width absent so the matcher falls back to exact equality.
+    width_query = _tmux_pane_width(pane_target)
+    trust_state = dict(state) if isinstance(state, dict) else {}
+    if width_query.get("ok"):
+        trust_state["pane_width"] = width_query["pane_width"]
+    answer = attempt_trust_auto_answer(
+        workspace,
+        pane_target,
+        injection.get("pane_capture_tail") or "",
+        event_log,
+        state=trust_state,
+    )
+    if not answer.get("answered"):
+        return injection
+    if not _wait_for_trust_prompt_dismissal(injection.get("pane_id") or target, timeout=3.0):
+        retry_blocked = dict(injection)
+        retry_blocked["error"] = "trust_prompt_not_dismissed_after_answer"
+        retry_blocked["verification"] = "trust_prompt_not_dismissed_after_answer"
+        retry_blocked["stage"] = "trust_auto_answer_dismissal_wait"
+        return retry_blocked
+    return _tmux_inject_text(
+        target,
+        text,
+        submit_key,
+        buffer_name,
+        provider=provider,
+    )

package/src/team_agent/provider_state/README.md

@@ -0,0 +1,78 @@
+# Adding a provider idle/turn-state adapter
+
+Gap 32 decides every node's idle/working/abnormal state from a deterministic
+FILE FACT — the provider's own session-log/rollout turn-lifecycle records — never
+from the pane screen. The predicate, abnormal track, and wake layers are
+**provider-neutral and reused unchanged**. To support a brand-new CLI you fill the
+small checklist below; you do not touch any neutral module.
+
+## What you add (only two places)
+
+1. `src/team_agent/provider_state/<provider>.py` — a thin reader that translates
+   that CLI's session records into normalized lifecycle facts.
+2. one entry in `src/team_agent/provider_state/registry.py` — pure infra DATA.
+
+Everything else (`idle_predicate.py`, `abnormal_track.py`, `wake.py`,
+`idle_takeover.py`) is provider-neutral and must stay free of provider names
+(there is a grep test, C6).
+
+## The checklist
+
+### 1. Session/rollout file location
+- Where does this CLI write its per-session log? (root dir + path layout)
+- How does the framework already learn each agent's path? (it is captured into
+  runtime state per agent as `rollout_path`; confirm yours lands there.)
+- Record it under the registry entry `file_location`.
+
+### 2. Turn-lifecycle event types (do the empirical capture FIRST)
+Capture REAL records from a live session for each state and record the exact
+record `type`/field. These become the contract fixtures (real-fixture-first):
+- **turn-started / open turn** — the marker that a turn is in flight.
+- **turn-complete** — the close that means idle.
+- **interrupted** — user ESC / abort (idle_interrupted, idle + red note).
+- **blocked / approval** — awaiting a human decision (blocked_on_human).
+- **error / failed** — a structured terminal fault record.
+Implement these as `extract_facts(records) -> (facts, diagnostics)` in your reader,
+emitting `team_agent.provider_state.common` fact kinds: `TURN_OPEN`,
+`TURN_COMPLETE`, `INTERRUPTED`, `FAILED`, `APPROVAL`, `ERROR`. Fault facts should
+carry `signature`, `turn_id`, and `raw` (the original record). Filter out trailing
+metadata/telemetry records so the verdict is the last LIFECYCLE fact, not the last
+physical line.
+
+Reference markers already implemented:
+- Claude transcript: assistant `stop_reason==end_turn` (idle) / `==tool_use`
+  (working); user text `[Request interrupted by user]` (interrupted); user
+  `tool_result is_error==true` and system `subtype==api_error,level==error` (faults).
+- Codex rollout: `event_msg payload.type==task_started|task_complete`;
+  `turn_aborted reason==interrupted`; app-server `turn.status==failed` and
+  `*/requestApproval`.
+
+### 3. Black/white list seed entries
+- `error_lists.whitelist` — record/string patterns that are benign → skip.
+- `error_lists.blacklist` — known error signatures → notify (`api error`,
+  `rate limit`, `overloaded`, traceback/panic, provider `failed`, ...).
+- Precedence is whitelist > blacklist > default-notify (catch-bias for structured
+  faults only). Lists are DATA — adding a pattern is one edit + one fixture.
+
+### 4. Optional hook accelerator
+- Does the CLI expose hooks that fire on turn boundaries (e.g. a `Stop`/`Notify`
+  program)? If so they can push a fact row to wake the watcher faster — but the
+  file fact remains the source of truth (the hook is validated against the file,
+  never the sole signal).
+
+### 5. Process/identity facts for the liveness guard
+- How to read the provider process identity (start-time / cmdline) so an open
+  turn whose process was replaced (PID reuse) classifies as `crashed_mid_turn`,
+  never eternal `working` (C4). `provider_state.common.process_is_live` already
+  implements the comparison given `{"expected": {...}, "current": {...}}`.
+
+## Reused unchanged (do NOT modify per provider)
+- `idle_predicate.evaluate_takeover_reminder` — all-idle + arm-after-delegation +
+  monotonic debounce + edge ack.
+- `abnormal_track.process_abnormal_records` / `detect_whole_team_gone` — dedup,
+  catch-bias, coordinator-independent whole-team-gone.
+- `wake` — file-change watch + mtime gate.
+- `idle_takeover` — the public facade.
+
+If you find yourself editing a neutral module to add a provider, stop — the fact
+you need belongs in the reader or the registry entry instead.

package/src/team_agent/provider_state/__init__.py

@@ -0,0 +1,86 @@
+"""Provider turn-state readers behind one shared interface (Gap 32 §6).
+
+``read_turn_state`` is the single entry the rest of the runtime uses; provider
+dispatch happens here (and in registry data), so the neutral predicate /
+abnormal / wake modules never name a provider.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import Any
+
+from team_agent.provider_state.registry import get_provider_registry
+
+_READER_CACHE: dict[str, Any] = {}
+
+
+def read_turn_state(
+    provider: str,
+    session_log_text: str,
+    *,
+    process: Any = None,
+    file_silence_seconds: float = 0,
+    registry: Any = None,
+) -> dict[str, Any]:
+    """Classify a node's turn state from its provider session-log text.
+
+    Returns the stable dict shape: state / turn_id / reason / source /
+    annotations / diagnostics. A missing/unknown provider or an unreadable
+    file fails safe to ``unknown`` (never idle, Gap 32 C5).
+    """
+    _ = file_silence_seconds  # open-turn beats silence (C14); silence never forces idle
+    reader = _reader_for(provider, registry)
+    if reader is None:
+        return {
+            "state": "unknown",
+            "turn_id": None,
+            "reason": "unknown_provider",
+            "source": "registry",
+            "annotations": [],
+            "diagnostics": [{"kind": "unknown_provider", "provider": provider}],
+        }
+    return reader.classify(session_log_text, process=process)
+
+
+def read_fault_facts(provider: str, records: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Extract normalized fault/approval facts from already-parsed provider
+    records, using the provider reader. The abnormal track consumes these
+    without naming a provider.
+    """
+    reader = _reader_for(provider)
+    if reader is None or not hasattr(reader, "extract_facts"):
+        return []
+    facts, _diag = reader.extract_facts(records or [])
+    fault_kinds = {"error", "failed", "approval"}
+    out: list[dict[str, Any]] = []
+    for fact in facts:
+        if fact.get("kind") in fault_kinds:
+            enriched = dict(fact)
+            enriched.setdefault("provider", provider)
+            out.append(enriched)
+    return out
+
+
+def _reader_for(provider: str, registry: Any = None) -> Any:
+    if provider in _READER_CACHE:
+        return _READER_CACHE[provider]
+    entry = None
+    if isinstance(registry, dict):
+        entry = registry.get(provider) if provider in registry else registry
+    if not isinstance(entry, dict) or "reader_module" not in entry:
+        entry = get_provider_registry(provider)
+    if not isinstance(entry, dict):
+        return None
+    module_name = entry.get("reader_module")
+    if not module_name:
+        return None
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        return None
+    _READER_CACHE[provider] = module
+    return module
+
+
+__all__ = ["read_turn_state", "read_fault_facts", "get_provider_registry"]