ccx-native 0.0.0-stage → 0.1.0

package/ccx/claude/host/subagents.py

@@ -0,0 +1,169 @@
+from __future__ import annotations
+from ccx.system import oslayer
+from ccx.claude.host.events import _event_preview, _hook_tool_result, _hook_tool_use_id, _tool_ok
+
+
+def _hook_subagent_id(data) -> str | None:
+    """The originating subagent of a hook payload, or None for the parent."""
+    if not isinstance(data, dict):
+        return None
+    for key in ("agent_id", "subagent_id", "agentId", "subagentId"):
+        value = data.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def _hook_subagent_type(data: dict) -> str | None:
+    for key in ("agent_type", "subagent_type", "agentType", "subagentType"):
+        value = data.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+def _subagent_tool_started_event(data: dict) -> dict:
+    """A subagent's tool start. Distinct from parent `tool_started`, and carries
+    no parent `turn`: subagent work belongs to no parent turn."""
+    return {
+        "type": "subagent_tool_started",
+        "agent_id": _hook_subagent_id(data),
+        "agent_type": _hook_subagent_type(data),
+        "tool_use_id": _hook_tool_use_id(data),
+        "tool": data.get("tool_name"),
+        "input_preview": _event_preview(data.get("tool_input")),
+    }
+
+
+def _subagent_tool_finished_event(data: dict, duration_ms: int | None) -> dict:
+    return {
+        "type": "subagent_tool_finished",
+        "agent_id": _hook_subagent_id(data),
+        "agent_type": _hook_subagent_type(data),
+        "tool_use_id": _hook_tool_use_id(data),
+        "tool": data.get("tool_name"),
+        "duration_ms": duration_ms,
+        "ok": _tool_ok(data),
+        "result_preview": _event_preview(_hook_tool_result(data)),
+    }
+
+
+def subagent_boundary_reply(data) -> dict | None:
+    """Hook-event reply for a subagent PostToolUse/SubagentStop, else None.
+
+    Steering is pasted only at the parent's own tool boundaries, where Claude's
+    main loop is paused on the hook."""
+    if _hook_subagent_id(data) is None:
+        return None
+    return {"ok": True, "delivered": False, "reason": "subagent hook"}
+
+
+def notification_sets_waiting(data) -> bool:
+    """Whether a Notification hook means the parent input surface is blocked.
+
+    Only the parent `permission_prompt` does. `worker_permission_prompt` is a
+    worker's prompt; its payload carries no `agent_id`, so it cannot be owned by
+    the parent and stays informational."""
+    return isinstance(data, dict) and data.get("notification_type") == "permission_prompt"
+
+
+ELICITATION_DIALOG_NOTIFICATIONS = ("elicitation_dialog", "elicitation_url_dialog")
+
+
+ELICITATION_SETTLED_NOTIFICATIONS = ("elicitation_response", "elicitation_complete")
+
+
+def notification_elicitation_dialog(data) -> bool:
+    """Whether a Notification hook reports an unbrokered elicitation dialog."""
+    return (isinstance(data, dict)
+            and data.get("notification_type") in ELICITATION_DIALOG_NOTIFICATIONS)
+
+
+def notification_elicitation_settled(data) -> bool:
+    """Whether a Notification hook reports that an elicitation was answered."""
+    return (isinstance(data, dict)
+            and data.get("notification_type") in ELICITATION_SETTLED_NOTIFICATIONS)
+
+
+def hook_fired_ms(data, received_ms: int) -> int:
+    """When the hook fired: the relay's stamp, else the host's receipt time."""
+    stamp = data.get("_ccx_relay_ms") if isinstance(data, dict) else None
+    if isinstance(stamp, int) and not isinstance(stamp, bool) and 0 < stamp <= received_ms:
+        return stamp
+    return received_ms
+
+
+def note_subagent_taint(taint: dict, event_name: str, data, now_ms: int) -> bool:
+    """Record evidence that a subagent may be running; True if taint began.
+
+    Claude's native presence (`sessions/<pid>.json` status) stays `busy` while
+    any subagent runs, so it cannot attribute activity to the parent. Every
+    subagent hook — including SubagentStop, since the agent was live until
+    then and presence lags — taints native evidence, as does a running
+    subagent in a parent Stop's `background_tasks` snapshot. Taint is never
+    removed by hook order (relays can reorder); only fresh native quiescence
+    clears it (clear_subagent_taint). `now_ms` is when the hook fired
+    (hook_fired_ms), so a late-delivered hook cannot outdate a later native
+    idle transition."""
+    was_tainted = bool(taint)
+    data = data if isinstance(data, dict) else {}
+    agent_id = _hook_subagent_id(data)
+    if agent_id is not None:
+        taint[agent_id] = max(taint.get(agent_id, 0), now_ms)
+    elif event_name == "Stop" and isinstance(data.get("background_tasks"), list):
+        for t in data["background_tasks"]:
+            if (
+                isinstance(t, dict) and t.get("type") == "subagent"
+                and t.get("status") == "running"
+                and isinstance(t.get("id"), str) and t.get("id")
+            ):
+                # Reordered delivery must never lower a fence.
+                taint[t["id"]] = max(taint.get(t["id"], 0), now_ms)
+    return bool(taint) and not was_tainted
+
+
+def clear_subagent_taint(taint: dict, value) -> bool:
+    """Clear the taint on native quiescence newer than every taint; True if cleared.
+
+    `idle`/`shell` means nothing — parent or subagent — is running, but only a
+    status written strictly after the latest subagent evidence proves it: an
+    older sample may predate an agent that has started since, and a
+    same-millisecond one cannot be ordered against it (the next native
+    transition will clear)."""
+    if not taint or value is None or value.status not in {"idle", "shell"}:
+        return False
+    updated = value.status_updated_at
+    if updated is None or updated <= max(taint.values()):
+        return False
+    taint.clear()
+    return True
+
+
+def _native_hook_descendant(peer_pid: int, worker_pid: int | None,
+                            worker_start: str | int | None) -> bool:
+    """Linux SO_PEERCRED peer must be the original native child or its relay.
+
+    Native hooks run either in the Claude process or a process it spawned.
+    Resolve at most 16 current /proc parent links with an immutable original
+    worker PID+start-time anchor, rejecting recycled PIDs and detached peers.
+    No owner/name/short/native-id inference is made from arbitrary processes.
+    """
+    from ccx.store.liveness import proc_start_token
+    if (not isinstance(peer_pid, int) or peer_pid < 2
+            or not isinstance(worker_pid, int) or worker_pid < 2
+            or not worker_start
+            or str(proc_start_token(worker_pid)) != str(worker_start)):
+        return False
+    seen = set()
+    current = peer_pid
+    for _ in range(16):
+        if current in seen or current < 2 or not proc_start_token(current):
+            return False
+        if current == worker_pid:
+            return str(proc_start_token(worker_pid)) == str(worker_start)
+        seen.add(current)
+        parent = oslayer.process_info(current).ppid  # kernel field 4
+        if parent is None:
+            return False
+        current = parent
+    return False

package/ccx/claude/host/successor.py

@@ -0,0 +1,267 @@
+from __future__ import annotations
+from ccx.constants import (
+    S,
+)
+from ccx.claude.transcript import (
+    is_compact_command_text,
+)
+
+
+def input_ready_pty_read(last_pty_read: float, subagent_tainted: bool,
+                         now: float, quiescence_s: float) -> float:
+    """The PTY-read time the Ink-ready quiescence gates should see.
+
+    A live subagent keeps Claude's TUI redrawing its progress while the parent
+    is idle, so PTY output stops proving Ink is mid-render and the gates would
+    starve every write until the agent ends. While tainted, the post-IDLE
+    `earliest_send_at` settle alone gates readiness; the paste ack/retry path
+    still catches a dropped paste."""
+    if subagent_tainted and last_pty_read > 0:
+        return min(last_pty_read, now - quiescence_s)
+    return last_pty_read
+
+
+def settling_grace_elapsed(state: dict, obs: dict | None, *,
+                           now: float, grace_s: float) -> bool:
+    """After draining ready hooks, only the same still-settling turn may commit.
+
+    A parent hook may reset the idle candidate while ingress is being drained.
+    Its missing timestamp must never be interpreted as a grace beginning at 0.
+    """
+    return bool(
+        obs is not None and obs is state.get("interrupt_observation")
+        and obs.get("settling") is True
+        and type(obs.get("settling_at")) in (float, int)
+        and obs["settling_at"] > 0
+        and state.get("settling_turn_ref") == obs.get("turn_ref")
+        and state.get("active_turn_ref") == obs.get("turn_ref")
+        and now - obs["settling_at"] >= grace_s
+    )
+
+
+def interrupt_native_idle_after_escape(state: dict, obs: dict | None, value) -> bool:
+    """An exact active turn is inactive on original native IDLE after ESC.
+
+    Claude's interactive session status describes all work, including agents:
+    native BUSY is ambiguous under subagent taint, but IDLE/SHELL means nothing
+    is running. No prior BUSY observation or taint-clear is required. Preserve
+    exact target identity and the actual ESC-write timestamp as the only fence.
+    """
+    return bool(
+        obs and not obs.get("settling")
+        and (state.get("current") in (S.BUSY, S.WAITING)
+             if obs.get("passive") else state.get("current") == S.BUSY)
+        and isinstance(obs.get("turn_ref"), str) and obs["turn_ref"]
+        and state.get("active_turn_ref") == obs["turn_ref"]
+        and type(obs.get("interrupt_at_ms")) is int
+        and obs["interrupt_at_ms"] > 0
+        and value is not None
+        and (value.status == "idle" if obs.get("passive")
+             else value.status in {"idle", "shell"})
+        and (not obs.get("passive") or not getattr(value, "waiting_for", None))
+        and type(value.status_updated_at) is int
+        and value.status_updated_at > obs["interrupt_at_ms"]
+    )
+
+
+def bind_accepted_original_new_turn(
+    state: dict, receipt: dict, *, turn_ref: str,
+    native_user_event: dict | None,
+    delivery_host_epoch: str | None, current_host_epoch: str,
+) -> bool:
+    """Bind a late-accepted original to its already started generic turn.
+
+    The caller matched this event against the pinned original Claude native
+    transcript. Never attribute a steer, old-host recovery or second original
+    to an active turn: the actual session-bound Stop still must settle it.
+    """
+    if (
+        state.get("current") != S.BUSY
+        or state.get("active_turn_ref") != turn_ref
+        or state.get("active_turn_delivery_id") is not None
+        or not isinstance(native_user_event, dict)
+        or type(native_user_event.get("offset")) is not int
+        or native_user_event["offset"] <= 0
+        or not current_host_epoch
+        or delivery_host_epoch != current_host_epoch
+        or receipt.get("state") != "accepted"
+        or receipt.get("route") != "new_turn"
+        or receipt.get("placement") != "new_turn"
+        or receipt.get("turnRef") != turn_ref
+        or receipt.get("evidence") not in {"user-event", "started"}
+        # Hot `started` includes queued/dequeue hints. Only a separately
+        # re-read original ordinary USER row may bind the active turn.
+        or (receipt.get("evidence") == "started"
+            and native_user_event.get("kind") != "native-started-user")
+        or receipt.get("evidenceOffset") != native_user_event["offset"]
+        or receipt.get("evidenceUuid") != native_user_event.get("uuid")
+    ):
+        return False
+    delivery_id = receipt.get("deliveryId")
+    if not isinstance(delivery_id, str) or not delivery_id:
+        return False
+    state["active_turn_delivery_id"] = delivery_id
+    return True
+
+
+def hook_prompt_id(data: dict) -> str | None:
+    """Claude's per-user-prompt id carried by parent turn hooks, if any."""
+    value = data.get("prompt_id")
+    return value if isinstance(value, str) and value else None
+
+
+def guarded_hook_is_late_while_tainted(
+    event_name: str,
+    active_turn_ref: str | None,
+    hook_prompt_id: str | None,
+    settled_prompt_ids,
+) -> bool:
+    """Late-hook classification while native presence is subagent-tainted.
+
+    Native busy edges cannot be attributed, so the hook's own `prompt_id`
+    decides when both it and the settled target's are known: a hook of a
+    prompt the settled turn carried is late, any other is genuine (e.g. a fast
+    successor's Stop). Without that correlation the guard stays conservative for its short
+    backstop window: with a successor ref an old Stop is suppressed; without
+    one, a Stop/PreToolUse is treated as the settled target's delayed hook."""
+    if hook_prompt_id and settled_prompt_ids:
+        return hook_prompt_id in settled_prompt_ids
+    if active_turn_ref:
+        return event_name == "Stop"
+    return True
+
+
+def compact_settle_fence(operation: dict) -> int:
+    """Transcript offset past which a user prompt belongs to a new turn.
+
+    A settled compact operation records ``end_offset``: the byte just past its
+    own boundary record. Anything after that is not compaction's doing. Fall
+    back to the pre-paste ``fence_offset`` when a verdict carries no end offset
+    (a no-op has no boundary to end), which is conservative in the right
+    direction — a wider window can only include more of compaction's own
+    bookkeeping, and `foreign_prompt_since` already discounts all of it.
+    """
+    result = operation.get("result") or {}
+    for candidate in (result.get("end_offset"), operation.get("fence_offset")):
+        if isinstance(candidate, int) and candidate >= 0:
+            return candidate
+    return 0
+
+
+def successor_hold_should_release(
+    successor_pending: dict | None, active_turn_ref: str | None, native_status: str | None
+) -> bool:
+    """Should a BUSY/no-ref successor hold fall back to IDLE?"""
+    return bool(
+        successor_pending is not None
+        and not active_turn_ref
+        and native_status in {"idle", "shell"}
+    )
+
+
+def queued_steer_needs_successor_hold(slot: dict | None, turn_ref: str | None) -> bool:
+    """A steer queued before Stop may start without a second prompt hook."""
+    return bool(
+        slot is not None
+        and slot.get("route") == "steer"
+        and slot.get("target_turn_ref") == turn_ref
+        and slot.get("maybe_written")
+        and slot.get("phase") in {"steer_boundary", "await_evidence"}
+    )
+
+
+def successor_hold_quiescence_is_fresh(
+    successor_pending: dict, value, taint: dict[str, int],
+) -> bool:
+    """Is an inactive native sample fresh enough to release a successor hold?
+
+    Untainted holds keep the baseline rule (any inactive sample). A hold that is
+    subagent-ambiguous, or any hold while a subagent is live (including one
+    created before taint began), needs quiescence ordered strictly after both
+    the subagent evidence and the hold's own busy edge.
+    """
+    if not taint and not successor_pending.get("subagent_ambiguous"):
+        return True
+    updated = value.status_updated_at if value is not None else None
+    if updated is None:
+        return False
+    if taint and updated <= max(taint.values()):
+        return False
+    busy_token = successor_pending.get("native_busy_status_updated_at")
+    return busy_token is None or updated > busy_token
+
+
+def input_surface_write_blocked(state: dict) -> bool:
+    """Whether CCX-owned cleanup currently forbids prompt bytes reaching Ink.
+
+    Admission stays open: durable semantic sends may be owned while this is true,
+    but every PTY write pump/boundary writer must wait until cleanup releases.
+    """
+    return state.get("compact_clear") is not None or state.get("cancel_clear") is not None
+
+
+def post_compact_hold_may_release(
+    now: float, last_activity: float, last_pty_read: float, tainted: bool,
+    grace_s: float,
+) -> bool:
+    """May the post-compact BUSY hold fall back to IDLE on silence?
+
+    The hold is backed by evidence of a parent turn. Untainted, combined hook
+    and PTY silence past the grace proves no turn runs. While a subagent is
+    live neither signal is parent-specific: the child keeps Ink redrawing, and
+    a parent in a long tool or model wait is silent in hooks and transcript.
+    The hold then waits for parent terminal evidence or fresh quiescence
+    (which clears the taint and restores the silence rule).
+    """
+    if tainted:
+        return False
+    return now - max(last_activity, last_pty_read) > grace_s
+
+
+def successor_attribution(inactive_token: int | None, value) -> tuple[bool, int | None]:
+    """Classify a native busy edge seen after a settling target went inactive.
+
+    Returns ``(successor, successor_token)``: a busy token newer than the
+    target's inactive edge may be queued parent work. With a subagent live the
+    aggregate presence cannot tell parent from child, and neither IDLE nor a
+    timeout is safe, so the caller still holds BUSY (marked ambiguous) until a
+    parent UPS attributes it or fresh native quiescence releases it.
+    """
+    if (
+        value is None or value.status != "busy"
+        or value.status_updated_at is None
+        or value.status_updated_at <= int(inactive_token or 0)
+    ):
+        return False, None
+    return True, value.status_updated_at
+
+
+def compact_displaced_by_prompt(state: dict, prompt) -> bool:
+    """Did an ordinary user turn just take the input surface from our paste?
+
+    ``/compact`` is pasted without its Enter and submitted by a delayed,
+    retried keypress (Ink's autocomplete menu eats a same-write ``\\r``).  That
+    leaves a window in which Claude can flush a prompt it had queued from an
+    earlier steer: the queued prompt runs as an ordinary turn and our command
+    text is left sitting in the editor, never to be submitted.
+
+    A ``UserPromptSubmit`` carrying non-``/compact`` text during that window is
+    positive proof of exactly that.  It is the only signal that distinguishes
+    the case from native compaction (which also emits hook traffic while it
+    summarizes), and without it the operation can only die at its timeout —
+    twenty minutes of a caller blocking on a command that already failed.
+
+    Deliberately narrow.  Once submission is acknowledged the native command
+    owns the surface and later hook traffic is compaction's own, so an
+    acknowledged operation is never displaced.
+    """
+    compacting = state.get("compacting")
+    if compacting is None:
+        return False
+    if compacting.get("submitted"):
+        return False
+    if compacting.get("pasted_at") is None:
+        # Nothing has been written to the editor yet, so nothing was displaced;
+        # the pump's own gate still owns the decision to paste.
+        return False
+    return not is_compact_command_text(prompt)

package/ccx/claude/managed_turns.py

@@ -0,0 +1,240 @@
+"""Authoritative managed-Claude turn boundaries from the host event sidecar.
+
+The managed host owns the worker-turn counter. Transcript prompts are not turn
+identities: Claude can persist /compact, task notifications, queued commands and
+other user-like records that do not correspond 1:1 with host turn boundaries.
+
+``turn_complete`` is semantic completion/interruption evidence.
+``turn_settled`` is liveness-only terminal evidence whose semantic outcome is
+unknown; it never proves a semantic completion. Exact report windows come from
+the transcript byte offsets recorded at each managed turn's start, not from
+terminal timestamps.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from typing import Any
+
+from ccx.store.paths import events_ndjson_path
+
+
+def new_turn_ref() -> str:
+    """Mint one opaque, start-unique managed-Claude turn identity."""
+    return f"ccx-turn:claude:v1:{uuid.uuid4()}"
+
+
+def _ts_ms(value: Any) -> int | None:
+    if not isinstance(value, (int, float)) or isinstance(value, bool):
+        return None
+    # Host broadcast timestamps are wall-clock seconds. Accept milliseconds as
+    # well so fixtures/future writers can use the record convention directly.
+    return int(value * 1000) if abs(float(value)) < 10_000_000_000 else int(value)
+
+
+def _terminal_events(short: str) -> list[dict[str, Any]] | None:
+    """Normalized retained managed-turn terminals in sidecar order.
+
+    ``None`` means the sidecar itself is unavailable. ``[]`` means it exists but
+    currently contains no retained managed turn terminal.
+    """
+    path = events_ndjson_path(short)
+    if not path.exists():
+        return None
+    out: list[dict[str, Any]] = []
+    try:
+        with path.open(encoding="utf-8") as handle:
+            for line in handle:
+                try:
+                    value = json.loads(line)
+                except (TypeError, ValueError):
+                    continue
+                if not isinstance(value, dict):
+                    continue
+                event_type = value.get("type")
+                if event_type not in {"turn_complete", "turn_settled"}:
+                    continue
+                turn = value.get("turn")
+                if not isinstance(turn, int) or isinstance(turn, bool) or turn <= 0:
+                    continue
+                settled_at_ms = _ts_ms(value.get("ts"))
+                if settled_at_ms is None:
+                    continue
+                if event_type == "turn_complete":
+                    interrupted = bool(value.get("interrupted", False))
+                    outcome = "interrupted" if interrupted else "completed"
+                else:
+                    interrupted = None
+                    outcome = value.get("outcome") or "unknown"
+                    if outcome not in {"completed", "interrupted", "unknown"}:
+                        outcome = "unknown"
+                item: dict[str, Any] = {
+                    "turn": turn,
+                    "settledAtMs": settled_at_ms,
+                    "epoch": value.get("epoch"),
+                    "seq": value.get("seq"),
+                    "eventType": event_type,
+                    "outcome": outcome,
+                }
+                if interrupted is not None:
+                    item["interrupted"] = interrupted
+                    item["completedAtMs"] = settled_at_ms
+                if isinstance(value.get("turn_ref"), str) and value.get("turn_ref"):
+                    item["turnRef"] = value["turn_ref"]
+                if event_type == "turn_settled":
+                    if isinstance(value.get("evidence"), str) and value.get("evidence"):
+                        item["evidence"] = value["evidence"]
+                    if isinstance(value.get("native_status"), str) and value.get("native_status"):
+                        item["nativeStatus"] = value["native_status"]
+                out.append(item)
+    except OSError:
+        return None
+    return out
+
+
+def turn_settlements(short: str) -> list[dict[str, Any]] | None:
+    """Return all retained managed turn terminal boundaries in sidecar order."""
+    values = _terminal_events(short)
+    return None if values is None else [dict(value) for value in values]
+
+
+def latest_settled_turn(
+    short: str, *, fallback: int = 0, record_last_settled_at_ms: int | None = None
+) -> int:
+    """Latest host-owned settled turn, with a fail-open record fallback.
+
+    ``lastSettledAt`` is written before the terminal event. If the retained
+    sidecar's latest terminal predates that record timestamp, the sidecar is
+    known stale/incomplete and must not decrement a valid persisted ordinal.
+    """
+    values = turn_settlements(short)
+    if values:
+        latest = values[-1]
+        if (
+            isinstance(record_last_settled_at_ms, int)
+            and int(latest["settledAtMs"]) < record_last_settled_at_ms
+        ):
+            return max(0, int(fallback or 0))
+        return int(latest["turn"])
+    return max(0, int(fallback or 0))
+
+
+def _with_previous_settlement(values: list[dict[str, Any]], index: int) -> dict[str, Any]:
+    result = dict(values[index])
+    result["previousSettledAtMs"] = (
+        int(values[index - 1]["settledAtMs"]) if index > 0 else None
+    )
+    return result
+
+
+def settlement_for_turn(
+    short: str, turn_number: int
+) -> tuple[dict[str, Any] | None, bool]:
+    """Exact retained managed terminal for one lifecycle ordinal."""
+    values = turn_settlements(short)
+    if values is None:
+        return None, False
+    for index in range(len(values) - 1, -1, -1):
+        if values[index]["turn"] == turn_number:
+            return _with_previous_settlement(values, index), True
+    return None, True
+
+
+def settlement_for_turn_ref(
+    short: str, turn_ref: str
+) -> tuple[dict[str, Any] | None, bool]:
+    """Exact retained managed terminal for one start-unique turn ref."""
+    values = turn_settlements(short)
+    if values is None:
+        return None, False
+    for index in range(len(values) - 1, -1, -1):
+        if values[index].get("turnRef") == turn_ref:
+            return _with_previous_settlement(values, index), True
+    return None, True
+
+
+def report_window_for_turn_ref(
+    short: str, turn_ref: str
+) -> tuple[dict[str, Any] | None, bool]:
+    """Exact retained Claude transcript window metadata for one managed turn.
+
+    ``None, False`` means the sidecar is unavailable. ``None, True`` means the
+    sidecar exists but has never heard of this turn ref. A returned dict may have
+    ``startOffset=None`` when CCX only recovered the turn identity after output
+    had already begun; callers must treat that as unavailable rather than guess.
+
+    The upper bound is the first later managed-turn identity. If that later turn
+    lacks an exact start offset, ``endOffsetKnown`` is false: reading to current
+    EOF would cross a known turn boundary and is forbidden.
+    """
+    path = events_ndjson_path(short)
+    if not path.exists():
+        return None, False
+    starts: list[dict[str, Any]] = []
+    terminal: dict[str, Any] | None = None
+    seen_ref = False
+    try:
+        with path.open(encoding="utf-8") as handle:
+            for index, line in enumerate(handle):
+                try:
+                    value = json.loads(line)
+                except (TypeError, ValueError):
+                    continue
+                if not isinstance(value, dict):
+                    continue
+                ref = value.get("turn_ref")
+                if not isinstance(ref, str) or not ref:
+                    continue
+                event_type = value.get("type")
+                if event_type in {"turn_start", "turn_identity_recovered"}:
+                    raw_offset = value.get("report_start_offset")
+                    offset = (
+                        raw_offset
+                        if isinstance(raw_offset, int)
+                        and not isinstance(raw_offset, bool)
+                        and raw_offset >= 0
+                        else None
+                    )
+                    starts.append({
+                        "turnRef": ref,
+                        "startOffset": offset,
+                        "lineIndex": index,
+                    })
+                    if ref == turn_ref:
+                        seen_ref = True
+                    continue
+                if event_type in {"turn_complete", "turn_settled"} and ref == turn_ref:
+                    terminal = dict(value)
+                    terminal["_ccx_line_index"] = index
+                    seen_ref = True
+    except OSError:
+        return None, False
+
+    if not seen_ref:
+        return None, True
+
+    start = next((value for value in starts if value["turnRef"] == turn_ref), None)
+    start_offset = start.get("startOffset") if start is not None else None
+    terminal_index = (
+        terminal.get("_ccx_line_index") if isinstance(terminal, dict) else None
+    )
+    end_offset = None
+    end_offset_known = True
+    if isinstance(terminal_index, int):
+        for value in starts:
+            if value["lineIndex"] <= terminal_index or value["turnRef"] == turn_ref:
+                continue
+            if value.get("startOffset") is None:
+                end_offset_known = False
+            else:
+                end_offset = value["startOffset"]
+            break
+
+    return {
+        "turnRef": turn_ref,
+        "startOffset": start_offset,
+        "endOffset": end_offset,
+        "endOffsetKnown": end_offset_known,
+        "settled": terminal is not None,
+    }, True