@team-agent/installer 0.2.3 → 0.2.4

package/src/team_agent/message_store/leader_notification_log.py

@@ -11,9 +11,20 @@ from __future__ import annotations
 
 from contextlib import closing
 from datetime import datetime, timedelta, timezone
+import sqlite3
+import time
 from typing import Any
 
 
+def _sqlite_locked(exc: sqlite3.OperationalError) -> bool:
+    message = str(exc).lower()
+    return (
+        "database is locked" in message
+        or "database table is locked" in message
+        or "database schema is locked" in message
+    )
+
+
 def claim_leader_notification_delivery(
     store: Any,
     *,
@@ -28,32 +39,42 @@ def claim_leader_notification_delivery(
     rowcount=0 means a prior row exists for (result_id, leader_session_uuid); SELECT
     it and return so the caller can decide to suppress (same envelope_hash) or surface
     legitimate-duplicate (different envelope_hash)."""
-    now = datetime.now(timezone.utc).isoformat()
-    with closing(store.connect()) as conn:
-        with conn:
-            cur = conn.execute(
-                "insert or ignore into leader_notification_log("
-                "  result_id, leader_session_uuid, notified_message_id, notified_at,"
-                "  leader_pane_id_at_notify, envelope_content_hash, owner_team_id"
-                ") values (?, ?, ?, ?, ?, ?, ?)",
-                (
-                    result_id, leader_session_uuid, proposed_message_id, now,
-                    pane_id, envelope_hash, owner_team_id,
-                ),
-            )
-            if cur.rowcount == 1:
-                return {
-                    "status": "claimed_by_you",
-                    "notified_message_id": proposed_message_id,
-                    "notified_at": now,
-                    "envelope_content_hash": envelope_hash,
-                }
-            row = conn.execute(
-                "select notified_message_id, notified_at, envelope_content_hash, "
-                "leader_pane_id_at_notify from leader_notification_log "
-                "where result_id = ? and leader_session_uuid = ?",
-                (result_id, leader_session_uuid),
-            ).fetchone()
+    delay = 0.05
+    row = None
+    for attempt in range(6):
+        now = datetime.now(timezone.utc).isoformat()
+        try:
+            with closing(store.connect()) as conn:
+                with conn:
+                    cur = conn.execute(
+                        "insert or ignore into leader_notification_log("
+                        "  result_id, leader_session_uuid, notified_message_id, notified_at,"
+                        "  leader_pane_id_at_notify, envelope_content_hash, owner_team_id"
+                        ") values (?, ?, ?, ?, ?, ?, ?)",
+                        (
+                            result_id, leader_session_uuid, proposed_message_id, now,
+                            pane_id, envelope_hash, owner_team_id,
+                        ),
+                    )
+                    if cur.rowcount == 1:
+                        return {
+                            "status": "claimed_by_you",
+                            "notified_message_id": proposed_message_id,
+                            "notified_at": now,
+                            "envelope_content_hash": envelope_hash,
+                        }
+                    row = conn.execute(
+                        "select notified_message_id, notified_at, envelope_content_hash, "
+                        "leader_pane_id_at_notify from leader_notification_log "
+                        "where result_id = ? and leader_session_uuid = ?",
+                        (result_id, leader_session_uuid),
+                    ).fetchone()
+            break
+        except sqlite3.OperationalError as exc:
+            if not _sqlite_locked(exc) or attempt == 5:
+                raise
+            time.sleep(delay)
+            delay *= 2
     if row is None:
         # Should not happen (INSERT OR IGNORE returned 0 → row must exist), but be defensive.
         return {"status": "claimed_by_you", "notified_message_id": proposed_message_id,

package/src/team_agent/messaging/delivery.py

@@ -15,6 +15,40 @@ from pathlib import Path
 from typing import Any
 
 
+def _tmux_pane_width(target: str) -> dict[str, Any]:
+    """Query the tmux pane width (display columns) for ``target``.
+
+    Live wiring seam for the trust-prompt truncation matcher: returns
+    ``{"ok": True, "pane_width": <int>}`` on success or
+    ``{"ok": False, "error": "..."}`` on any failure / timeout / unparseable
+    output. Fail-safe by design: NEVER returns a default width. Callers must
+    treat failure as "no boundary signal" and let the workspace matcher fall
+    back to exact equality, so a hard-truncated prompt is never auto-answered
+    on guesswork.
+    """
+    from team_agent.messaging.deps import run_cmd
+    try:
+        proc = run_cmd(
+            ["tmux", "display-message", "-p", "-t", str(target), "-F", "#{pane_width}"],
+            timeout=2,
+        )
+    except Exception as exc:  # pragma: no cover - defensive; tmux not present, timeout, etc.
+        return {"ok": False, "error": f"tmux_query_failed:{exc.__class__.__name__}"}
+    if getattr(proc, "returncode", 1) != 0:
+        err = (getattr(proc, "stderr", "") or "").strip().splitlines()
+        return {"ok": False, "error": err[0] if err else "tmux_query_nonzero"}
+    text = (getattr(proc, "stdout", "") or "").strip()
+    if not text:
+        return {"ok": False, "error": "empty_output"}
+    try:
+        width = int(text.splitlines()[0].strip())
+    except (ValueError, IndexError):
+        return {"ok": False, "error": "unparseable_output"}
+    if width <= 0:
+        return {"ok": False, "error": "non_positive_width"}
+    return {"ok": True, "pane_width": width}
+
+
 # Spark MEDIUM sweep #3 (2026-05-26): retry_needed bounded backoff. Each entry is
 # the delay (seconds) BEFORE the attempt with that number runs; attempt 1 was the
 # original delivery, attempt 2 fires 5s after retry_needed, attempt 3 fires 15s
@@ -85,12 +119,21 @@ def _deliver_pending_message(
         # Bypassed entirely when opt-out (default) — the existing failed envelope
         # is preserved.
         from team_agent.messaging.leader_panes import attempt_trust_auto_answer
+        pane_target = injection.get("pane_id") or target
+        # Live wiring: query the tmux pane width now and hand it to the trust
+        # matcher via state["pane_width"]. On failure we leave pane_width
+        # absent so the matcher falls back to exact equality (fail-safe — a
+        # right-edge truncated prefix is never auto-answered on guesswork).
+        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,
-            injection.get("pane_id") or target,
+            pane_target,
             injection.get("pane_capture_tail") or "",
             EventLog(workspace),
-            state=state,
+            state=trust_state,
         )
         if answer.get("answered"):
             # Spark MEDIUM #4 (2026-05-26): replace the fixed 0.3s sleep with a

package/src/team_agent/messaging/leader_panes.py

@@ -392,6 +392,9 @@ def _broadcast_ambiguous_candidates(
         team_id=team_id,
         uuid_prefix=_uuid_prefix(owner_identity),
         debounce_bucket=bucket,
+        # C16/C22: two or more live candidates remain; each must explicitly claim
+        # with --confirm, so the broadcast carries the closed-enum lease reason.
+        reason="force_confirm_required",
     )
     for candidate in candidates:
         pane_id = str(candidate.get("pane_id") or "")
@@ -560,7 +563,8 @@ def attempt_trust_auto_answer(
             reason="pane_id_missing",
         )
         return {"ok": False, "answered": False, "reason": "pane_id_missing"}
-    if not _capture_tail_references_workspace(pane_capture_tail, workspace):
+    pane_width = state.get("pane_width") if isinstance(state, dict) else None
+    if not _capture_tail_references_workspace(pane_capture_tail, workspace, pane_width):
         event_log.write(
             "leader_panes.trust_auto_answer_refused",
             pane_id=pane_id,
@@ -568,9 +572,15 @@ def attempt_trust_auto_answer(
             reason="workspace_dir_mismatch",
         )
         return {"ok": False, "answered": False, "reason": "workspace_dir_mismatch"}
+    # Round-5 (post Round-1..4 withdrawal): Codex's trust prompt already
+    # highlights `1. Yes, continue` as the default choice; a plain Enter
+    # accepts it. Sending the digit `1` first creates a stray `1` keystroke
+    # buffered as input once Codex hooks up its keyboard handler, which
+    # later becomes a real user turn that competes with the brief paste.
+    # Drop the digit; submit Enter only.
     answer = _tmux_inject_text(
         str(pane_id),
-        "1",
+        "",
         "Enter",
         f"team-agent-trust-auto-answer-{str(pane_id).strip('%') or 'pane'}",
         attempts=1,
@@ -653,44 +663,128 @@ def _reset_spec_opt_in_deprecation_state() -> None:
     _SPEC_OPT_IN_DEPRECATION_WARNED = False
 
 
-def _capture_tail_references_workspace(tail: str, workspace: Path) -> bool:
-    """Spark MEDIUM #5: a raw substring match accepted '/repo' inside
-    '/repo-backup' and rejected symlinked / trailing-slash spellings. We now
-    canonicalize the workspace via Path.resolve, parse candidate absolute paths
-    out of the prompt tail (one token per line after stripping codex box-drawing
-    glyphs), canonicalize each candidate the same way, and only return True on
-    boundary-safe canonical equality."""
+def _capture_tail_references_workspace(tail: str, workspace: Path, pane_width: int | None = None) -> bool:
+    """Decide whether the Codex trust-prompt tail names the worker's own
+    workspace cwd. The runtime cwd is the source of truth; the prompt path is a
+    consistency guard. Match cases (one converged helper per token):
+
+      - exact canonical equality (the unchanged baseline);
+      - mid-ellipsis ``head…tail`` / ``head...tail`` where head is a prefix of
+        the runtime cwd and tail is its suffix;
+      - hard right-edge truncation: the canonical runtime cwd starts with the
+        canonical captured path AND the captured token reaches the capture
+        line's right boundary (pane_width).
+
+    Without a pane_width signal, prefix matching is forbidden — the captured
+    path is treated as a complete token and must exactly equal the runtime cwd
+    (this is what stops ``/repo`` from sliding into ``/repo-backup``).
+    """
     if not tail:
         return False
     workspace_canonical = _canonicalize_path(workspace)
     if not workspace_canonical:
         return False
-    for candidate in _candidate_paths_from_prompt(tail):
-        if _canonicalize_path(Path(candidate)) == workspace_canonical:
+    for token, source_line in _candidate_path_lines_from_prompt(tail):
+        if _workspace_matches_token(workspace_canonical, token, source_line, pane_width):
             return True
     return False
 
 
-_PATH_LINE_RE = re.compile(r"(/[\w\-./~+@]+)")
+_PATH_LINE_RE = re.compile(r"(/[\w\-./~+@…]+)")
+_ELLIPSIS_TOKENS = ("…", "...")
 
 
-def _candidate_paths_from_prompt(tail: str) -> list[str]:
-    """Pull every absolute-path-shaped token out of the prompt's tail. Codex
-    renders the trust prompt's directory inside box-drawing glyphs and on its
-    own line; strip leading/trailing whitespace and glyph noise before matching."""
-    paths: list[str] = []
+def _candidate_path_lines_from_prompt(tail: str) -> list[tuple[str, str]]:
+    """Pull (path_token, source_line) pairs out of the prompt's tail. The
+    source line is the line AFTER stripping Codex box-drawing glyphs, so the
+    matcher can locate the token's end column relative to the visible width."""
+    pairs: list[tuple[str, str]] = []
+    seen: set[tuple[str, str]] = set()
     for raw_line in tail.splitlines():
         line = raw_line.strip()
-        # Codex draws box-glyph prefixes (▌ ▎ │) that need to be stripped.
         for glyph in ("▌", "▎", "│"):
             line = line.lstrip(glyph).strip()
         if not line:
             continue
         for match in _PATH_LINE_RE.finditer(line):
             token = match.group(1).rstrip("/")
-            if token and token not in paths:
-                paths.append(token)
-    return paths
+            if not token:
+                continue
+            key = (token, line)
+            if key in seen:
+                continue
+            seen.add(key)
+            pairs.append(key)
+    return pairs
+
+
+def _candidate_paths_from_prompt(tail: str) -> list[str]:
+    """Backwards-compatible token-only view (kept for any external callers)."""
+    out: list[str] = []
+    for token, _line in _candidate_path_lines_from_prompt(tail):
+        if token not in out:
+            out.append(token)
+    return out
+
+
+def _workspace_matches_token(
+    workspace_canonical: str,
+    token: str,
+    source_line: str,
+    pane_width: int | None,
+) -> bool:
+    """The converged trust-prompt match logic.
+
+    Order matters:
+      1. exact canonical equality;
+      2. mid-ellipsis head/tail match;
+      3. right-edge hard truncation (prefix + boundary-reached).
+    A captured token that does NOT reach the line's right boundary is treated
+    as a complete short path and must equal the runtime cwd exactly.
+    """
+    # 1. Exact canonical equality.
+    captured_canonical = _canonicalize_path(Path(token))
+    if not captured_canonical:
+        return False
+    if captured_canonical == workspace_canonical:
+        return True
+    # 2. Mid-ellipsis: split on … or ..., require head ⊑ workspace and workspace ⊐ tail.
+    for ellipsis in _ELLIPSIS_TOKENS:
+        if ellipsis in token:
+            head, _, tail_part = token.partition(ellipsis)
+            head_canonical = _canonicalize_path(Path(head)) if head.startswith("/") else head
+            if not head_canonical or not tail_part:
+                return False
+            return (
+                workspace_canonical.startswith(head_canonical)
+                and workspace_canonical.endswith(tail_part)
+            )
+    # 3. Right-edge hard truncation: prefix + boundary.
+    if not _token_reaches_right_edge(token, source_line, pane_width):
+        # No boundary signal → captured must be a complete token; exact already
+        # failed → mismatch (this rejects /repo vs /repo-backup both ways).
+        return False
+    return (
+        workspace_canonical == captured_canonical
+        or workspace_canonical.startswith(captured_canonical + "/")
+        or workspace_canonical.startswith(captured_canonical)
+    )
+
+
+def _token_reaches_right_edge(token: str, source_line: str, pane_width: int | None) -> bool:
+    """The token reaches the capture line's right boundary iff the line is wide
+    enough to be at pane capacity AND the token sits flush against the line's
+    end. Without a pane_width we cannot prove truncation — return False so the
+    caller falls back to exact-equality (this is the C/repo vs C/repo-backup
+    safeguard)."""
+    if not pane_width or pane_width <= 0:
+        return False
+    rstripped = source_line.rstrip()
+    if not rstripped.endswith(token):
+        return False
+    # Allow a one-column tolerance for trailing whitespace stripped from the
+    # raw capture; the line must be at pane capacity to count as hard-cut.
+    return len(rstripped) >= max(1, pane_width - 1)
 
 
 def _canonicalize_path(p: Path | str) -> str:

package/src/team_agent/messaging/send.py

@@ -77,6 +77,7 @@ def _send_message_unlocked(
             return gate
     owner_team_id = team_state_key(state)
     leader_id = _leader_id(state, spec)
+    _flag_rebind_required_when_unbound_plain_shell_leader(workspace, state, spec, sender, leader_id, event_log)
 
     if isinstance(target, list):
         if watch_result:
@@ -134,6 +135,38 @@ def _send_message_unlocked(
     )
 
 
+def _flag_rebind_required_when_unbound_plain_shell_leader(
+    workspace: Path,
+    state: dict[str, Any],
+    spec: dict[str, Any],
+    sender: str,
+    leader_id: str,
+    event_log: EventLog,
+) -> None:
+    # Gap 39 C5: a leader send from a plain shell (no $TMUX_PANE) must never self-bind
+    # the caller as the leader receiver. When the lease is fully unbound, flag a
+    # rebind_required so the message stays queued and the operator knows to reconnect
+    # from a real tmux leader pane. Only fires for an unbound lease + no caller pane.
+    import os
+    from team_agent.messaging.deps import _leader_receiver_is_direct
+    if not _is_leader_sender(sender, leader_id):
+        return
+    if isinstance(state.get("team_owner"), dict) and state["team_owner"].get("pane_id"):
+        return
+    if _leader_receiver_is_direct(state.get("leader_receiver")):
+        return
+    if os.environ.get("TEAM_AGENT_LEADER_PANE_ID") or os.environ.get("TMUX_PANE"):
+        return
+    event_log.write(
+        "leader_receiver.rebind_required",
+        reason="not_in_tmux_pane",
+        old_pane_id=(state.get("leader_receiver") or {}).get("pane_id"),
+        new_pane_id=None,
+        team_id=team_state_key(state),
+        recovery_action="run team-agent claim-leader --confirm from the leader's tmux pane",
+    )
+
+
 def _send_single_message_unlocked(
     workspace: Path,
     state: dict[str, Any],

package/src/team_agent/messaging/tmux_io.py

@@ -32,6 +32,49 @@ def _tmux_inject_text(
     *,
     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]] = []
@@ -134,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,
@@ -142,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",

package/src/team_agent/messaging/trust_auto_answer.py

@@ -18,14 +18,22 @@ def retry_injection_after_trust_auto_answer(
     buffer_name: str,
     provider: str,
 ) -> dict[str, Any]:
-    from team_agent.messaging.delivery import _wait_for_trust_prompt_dismissal
+    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,
-        injection.get("pane_id") or target,
+        pane_target,
         injection.get("pane_capture_tail") or "",
         event_log,
-        state=state,
+        state=trust_state,
     )
     if not answer.get("answered"):
         return injection

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"]