@team-agent/installer 0.2.3 → 0.2.5

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

package/src/team_agent/provider_state/claude.py

@@ -0,0 +1,86 @@
+"""Claude transcript reader — the ONLY Claude-specific turn-state knowledge.
+
+Translates Claude transcript JSONL records into normalized lifecycle facts.
+Real markers (see turn-state-markers-evidence.md):
+  - assistant message.stop_reason == "tool_use"   -> open turn (working)
+  - assistant message.stop_reason == "end_turn"    -> turn complete (idle)
+  - user text == "[Request interrupted by user]"   -> interrupted
+  - user tool_result is_error == true              -> structured tool error
+  - system subtype == "api_error" and level=="error" -> provider api error
+Trailing metadata records (stop_hook_summary / turn_duration / last-prompt /
+ai-title / permission-mode / ...) are ignored for the turn verdict.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from team_agent.provider_state import common
+
+_INTERRUPT_TEXT = "[Request interrupted by user]"
+
+
+def extract_facts(records: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    facts: list[dict[str, Any]] = []
+    diagnostics: list[dict[str, Any]] = []
+    for record in records:
+        rtype = record.get("type")
+        message = record.get("message")
+        if rtype == "assistant" and isinstance(message, dict):
+            stop_reason = message.get("stop_reason")
+            turn_id = record.get("requestId") or record.get("uuid")
+            if stop_reason == "end_turn":
+                facts.append({"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "end_turn"})
+            elif stop_reason == "tool_use":
+                facts.append({"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "tool_use"})
+            elif stop_reason == "stop_sequence":
+                facts.append({"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "stop_sequence"})
+            # other/missing stop_reason on assistant is treated as an open turn fragment
+            elif stop_reason is None and isinstance(message.get("content"), list):
+                facts.append({"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "assistant_in_flight"})
+        elif rtype == "user" and isinstance(message, dict):
+            content = message.get("content")
+            if _content_has_interrupt(content):
+                facts.append({"kind": common.INTERRUPTED, "turn_id": record.get("uuid"), "reason": "user_interrupt"})
+            elif _content_has_tool_error(content):
+                facts.append({
+                    "kind": common.ERROR,
+                    # the turn being retried/affected, stable across records (C8 dedup)
+                    "turn_id": record.get("parentUuid") or record.get("uuid"),
+                    "reason": "tool_result_is_error",
+                    "signature": "tool_result_is_error",
+                    "raw": record,
+                })
+        elif rtype == "system" and record.get("subtype") == "api_error" and record.get("level") == "error":
+            facts.append({
+                "kind": common.ERROR,
+                # api_error retries within a session dedup on (signature, session) (C8)
+                "turn_id": record.get("sessionId") or record.get("parentUuid") or record.get("uuid"),
+                "reason": "api_error",
+                "signature": "api_error",
+                "raw": record,
+            })
+        # everything else (metadata, snapshots, titles) is ignored for the verdict
+    return facts, diagnostics
+
+
+def classify(session_log_text: str, *, process: Any = None) -> dict[str, Any]:
+    return common.classify_with_reader(extract_facts, session_log_text, process=process)
+
+
+def _content_has_interrupt(content: Any) -> bool:
+    if not isinstance(content, list):
+        return False
+    for item in content:
+        if isinstance(item, dict) and item.get("type") == "text" and item.get("text") == _INTERRUPT_TEXT:
+            return True
+    return False
+
+
+def _content_has_tool_error(content: Any) -> bool:
+    if not isinstance(content, list):
+        return False
+    for item in content:
+        if isinstance(item, dict) and item.get("type") == "tool_result" and item.get("is_error") is True:
+            return True
+    return False

package/src/team_agent/provider_state/codex.py

@@ -0,0 +1,84 @@
+"""Codex rollout reader — the ONLY Codex-specific turn-state knowledge.
+
+Translates Codex rollout JSONL (and app-server jsonrpc) records into normalized
+lifecycle facts. Real markers (see turn-state-markers-evidence.md):
+  - event_msg payload.type == "task_started"   -> open turn (working)
+  - event_msg payload.type == "task_complete"  -> turn complete (idle)
+  - event_msg payload.type == "turn_aborted" reason=="interrupted" -> interrupted
+App-server schema-derived markers:
+  - method "turn/completed" params.turn.status == "failed" -> failed/error
+  - method ".../requestApproval"                            -> approval block
+Telemetry (token_count, agent_message, patch_apply_end, ...) is not a close.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from team_agent.provider_state import common
+
+
+def extract_facts(records: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    facts: list[dict[str, Any]] = []
+    diagnostics: list[dict[str, Any]] = []
+    for record in records:
+        rtype = record.get("type")
+        payload = record.get("payload") if isinstance(record.get("payload"), dict) else None
+        if rtype == "event_msg" and payload is not None:
+            ptype = payload.get("type")
+            turn_id = payload.get("turn_id")
+            if ptype == "task_started":
+                facts.append({"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "task_started"})
+            elif ptype == "task_complete":
+                facts.append({"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "task_complete"})
+            elif ptype == "turn_aborted" and payload.get("reason") == "interrupted":
+                facts.append({"kind": common.INTERRUPTED, "turn_id": turn_id, "reason": "interrupted"})
+            elif ptype == "turn_aborted":
+                facts.append({"kind": common.INTERRUPTED, "turn_id": turn_id, "reason": str(payload.get("reason") or "aborted")})
+        elif _is_app_server(record):
+            fact = _app_server_fact(record)
+            if fact is not None:
+                facts.append(fact)
+        # response_item (assistant/user messages), token_count, etc. are not verdicts
+    return facts, diagnostics
+
+
+def classify(session_log_text: str, *, process: Any = None) -> dict[str, Any]:
+    return common.classify_with_reader(extract_facts, session_log_text, process=process)
+
+
+def _is_app_server(record: dict[str, Any]) -> bool:
+    return record.get("jsonrpc") == "2.0" and isinstance(record.get("method"), str)
+
+
+def _app_server_fact(record: dict[str, Any]) -> dict[str, Any] | None:
+    method = str(record.get("method") or "")
+    params = record.get("params") if isinstance(record.get("params"), dict) else {}
+    if method == "turn/completed":
+        turn = params.get("turn") if isinstance(params.get("turn"), dict) else {}
+        status = turn.get("status")
+        turn_id = turn.get("id")
+        if status == "failed":
+            return {
+                "kind": common.FAILED,
+                "turn_id": turn_id,
+                "reason": "turn_failed",
+                "signature": "turn_failed",
+                "raw": record,
+            }
+        if status == "completed":
+            return {"kind": common.TURN_COMPLETE, "turn_id": turn_id, "reason": "completed"}
+        if status == "interrupted":
+            return {"kind": common.INTERRUPTED, "turn_id": turn_id, "reason": "interrupted"}
+        if status == "inProgress":
+            return {"kind": common.TURN_OPEN, "turn_id": turn_id, "reason": "in_progress"}
+        return None
+    if method.endswith("requestApproval"):
+        return {
+            "kind": common.APPROVAL,
+            "turn_id": params.get("turnId") or params.get("turn_id"),
+            "reason": "approval_required",
+            "signature": "approval_required",
+            "raw": record,
+        }
+    return None

package/src/team_agent/provider_state/common.py

@@ -0,0 +1,207 @@
+"""Shared, provider-neutral plumbing for the turn-state readers.
+
+The per-provider readers (claude.py, codex.py) only translate their own record
+shapes into a normalized list of lifecycle facts; everything else — JSONL
+tail parsing, metadata filtering wiring, the verdict decision, and the
+process-identity liveness guard — lives here so it is written once.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Callable
+
+# Normalized lifecycle fact kinds emitted by every reader.
+TURN_OPEN = "turn_open"
+TURN_COMPLETE = "turn_complete"
+INTERRUPTED = "interrupted"
+FAILED = "failed"
+APPROVAL = "approval"
+ERROR = "error"  # non-closing structured error (e.g. transient api retry / tool is_error)
+
+_CLOSING = {TURN_COMPLETE, INTERRUPTED, FAILED}
+
+
+def parse_jsonl(text: str) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
+    """Parse JSONL text into (records, parse_diagnostics).
+
+    Lines that are blank are skipped. Lines that are not valid JSON objects are
+    collected as diagnostics rather than raising — the caller decides whether a
+    populated diagnostics list with zero usable records means ``unknown``.
+    """
+    records: list[dict[str, Any]] = []
+    diagnostics: list[dict[str, Any]] = []
+    for lineno, raw in enumerate(text.splitlines(), start=1):
+        line = raw.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (ValueError, TypeError):
+            diagnostics.append({"kind": "json_decode_error", "line": lineno})
+            continue
+        if not isinstance(obj, dict):
+            diagnostics.append({"kind": "non_object_record", "line": lineno})
+            continue
+        records.append(obj)
+    return records, diagnostics
+
+
+def decide_state(
+    facts: list[dict[str, Any]],
+    *,
+    process: Any = None,
+    parse_diagnostics: list[dict[str, Any]] | None = None,
+    had_records: bool,
+    extra_diagnostics: list[dict[str, Any]] | None = None,
+) -> dict[str, Any]:
+    """Turn a normalized fact stream into the public classify result.
+
+    Verdict = the LAST lifecycle fact, not the last physical record. An open
+    turn (a ``turn_open`` not yet closed) is a positive "still working" fact
+    that survives arbitrary file silence (Gap 32 C14); the only thing that can
+    demote it is a failed process-identity guard (Gap 32 C4).
+    """
+    diagnostics = list(parse_diagnostics or []) + list(extra_diagnostics or [])
+
+    lifecycle = [f for f in facts if f.get("kind") in (_CLOSING | {TURN_OPEN, APPROVAL})]
+    if not lifecycle:
+        # No turn-lifecycle fact at all. If the input was unreadable/empty or a
+        # changed format with no recognizable records, fail safe to unknown (C5).
+        reason = "no_turn_lifecycle_fact"
+        if not had_records:
+            reason = "unreadable_or_empty"
+        elif diagnostics:
+            reason = "unrecognized_format"
+        return _result("unknown", None, reason, "session_file", [], diagnostics)
+
+    last = lifecycle[-1]
+    kind = last.get("kind")
+    turn_id = last.get("turn_id")
+    reason = str(last.get("reason") or kind)
+
+    if kind == TURN_COMPLETE:
+        return _result("idle", turn_id, reason or "turn_complete", "session_file", [], diagnostics)
+    if kind == INTERRUPTED:
+        return _result("idle_interrupted", turn_id, reason or "interrupted", "session_file", ["interrupted"], diagnostics)
+    if kind == FAILED:
+        return _result("abnormal", turn_id, reason or "turn_failed", "session_file", ["turn_failed"], diagnostics)
+    if kind == APPROVAL:
+        return _result("blocked_on_human", turn_id, reason or "approval_required", "session_file", ["awaiting_approval"], diagnostics)
+
+    # kind == TURN_OPEN with no later close → open turn. To declare "working" we
+    # must POSITIVELY confirm the recorded process is still alive (C4 fail-safe);
+    # missing/partial identity cannot be optimistically read as working.
+    verdict, live_reason, live_diag = process_liveness(process)
+    if live_diag:
+        diagnostics = diagnostics + [live_diag]
+    if verdict == "alive":
+        return _result("working", turn_id, "open_turn", "session_file", [], diagnostics)
+    if verdict == "dead":
+        return _result("abnormal", turn_id, "crashed_mid_turn", "process_guard", ["crashed_mid_turn", live_reason], diagnostics)
+    # unverifiable: cannot confirm alive → fail safe to unknown, never working.
+    return _result("unknown", turn_id, "process_identity_unverified", "process_guard", ["process_identity_unverified", live_reason], diagnostics)
+
+
+_STRONG_IDENTITY_FIELDS = ("start_time", "cmdline", "create_time")
+
+
+def process_liveness(process: Any) -> tuple[str, str, dict[str, Any] | None]:
+    """Process-identity liveness guard (Gap 32 C4) — three-valued.
+
+    Returns (verdict, reason, diagnostic) where verdict is one of:
+      - ``"alive"``        — positively confirmed the same process is running
+      - ``"dead"``         — confirmed replaced/exited (identity mismatch or flag)
+      - ``"unverifiable"`` — identity missing/partial; CANNOT be read as working
+
+    Identity, not bare PID: aliveness must be affirmatively confirmed by a strong
+    identity field (start_time / cmdline / create_time) present and equal in BOTH
+    the recorded and the current snapshot. Missing/partial info is fail-safe
+    unverifiable, never optimistically "alive".
+
+    Accepted ``process`` shapes (any one):
+      - None / non-dict                      → unverifiable
+      - {"alive"|"running": bool}            → explicit
+      - {"identity_match": bool}             → explicit identity verdict
+      - {"expected"|"recorded": {...}, "current"|"observed": {...}}
+    """
+    if process is None or not isinstance(process, dict):
+        return "unverifiable", "process_identity_missing", {"kind": "process_identity_unverified"}
+    if process.get("alive") is False or process.get("running") is False:
+        return "dead", "process_not_running", {"kind": "process_dead", "detail": "not_running"}
+    if process.get("identity_match") is False:
+        return "dead", "process_identity_mismatch", {"kind": "process_identity_mismatch"}
+    if process.get("alive") is True or process.get("running") is True or process.get("identity_match") is True:
+        return "alive", "process_alive", None
+    recorded = process.get("recorded") if isinstance(process.get("recorded"), dict) else process.get("expected")
+    current = process.get("current") if isinstance(process.get("current"), dict) else process.get("observed")
+    if not (isinstance(recorded, dict) and isinstance(current, dict)):
+        return "unverifiable", "process_identity_partial", {"kind": "process_identity_unverified"}
+    if current.get("alive") is False or current.get("running") is False:
+        return "dead", "process_not_running", {"kind": "process_dead", "detail": "current_not_running"}
+    # Any shared strong identity field that DIFFERS = confirmed replacement.
+    for key in _STRONG_IDENTITY_FIELDS:
+        if key in recorded and key in current and recorded.get(key) != current.get(key):
+            return "dead", f"process_identity_mismatch:{key}", {
+                "kind": "process_identity_mismatch",
+                "field": key,
+                "recorded": recorded.get(key),
+                "current": current.get(key),
+            }
+    # Require at least one strong identity field present+equal in BOTH, with no
+    # recorded strong field missing from current (else we cannot confirm).
+    recorded_strong = [k for k in _STRONG_IDENTITY_FIELDS if k in recorded]
+    confirmed = [k for k in recorded_strong if k in current and recorded.get(k) == current.get(k)]
+    missing = [k for k in recorded_strong if k not in current]
+    if confirmed and not missing:
+        return "alive", "process_identity_match", None
+    return "unverifiable", "process_identity_partial", {
+        "kind": "process_identity_unverified",
+        "recorded_strong": recorded_strong,
+        "confirmed": confirmed,
+        "missing": missing,
+    }
+
+
+def process_is_live(process: Any) -> tuple[bool, str, dict[str, Any] | None]:
+    """Boolean wrapper used by conservative callers (e.g. whole-team-gone): a
+    process is treated as live unless it is CONFIRMED dead. Unverifiable counts
+    as live here so we never falsely declare the team gone."""
+    verdict, reason, diag = process_liveness(process)
+    return (verdict != "dead"), reason, diag
+
+
+def _result(
+    state: str,
+    turn_id: str | None,
+    reason: str,
+    source: str,
+    annotations: list[str],
+    diagnostics: list[dict[str, Any]],
+) -> dict[str, Any]:
+    return {
+        "state": state,
+        "turn_id": turn_id,
+        "reason": reason,
+        "source": source,
+        "annotations": list(annotations),
+        "diagnostics": list(diagnostics),
+    }
+
+
+def classify_with_reader(
+    extract_facts: Callable[[list[dict[str, Any]]], tuple[list[dict[str, Any]], list[dict[str, Any]]]],
+    session_log_text: str,
+    *,
+    process: Any = None,
+) -> dict[str, Any]:
+    """Run a provider reader's fact extractor through the shared pipeline."""
+    records, parse_diag = parse_jsonl(session_log_text or "")
+    facts, extra_diag = extract_facts(records)
+    return decide_state(
+        facts,
+        process=process,
+        parse_diagnostics=parse_diag,
+        had_records=bool(records),
+        extra_diagnostics=extra_diag,
+    )