glab-cli-extras 0.1.0__py3-none-any.whl

glab_cli_extras/resources/pipeline.py

@@ -0,0 +1,319 @@
+"""Pipeline watching through GitLab's GraphQL ETag cache.
+
+Each poll sends the whole pipeline-tree query with `X-GITLAB-GRAPHQL-RESOURCE-ETAG: pipelines/id/<id>` and
+`If-None-Match`. GitLab answers an unchanged pipeline with a 304 from its cache before running the query, and touches
+the key on every job transition of the pipeline and its downstream pipelines. So one request is both the probe and
+the fetch. If the server sends no ETag, the poller falls back to plain polling at a slower interval.
+
+A job that ends and needs its log (per `--logs`) holds back its `job_finished` event until the log is in the cache,
+a few seconds later, so the event can carry the log path.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field, replace
+from typing import Any, ClassVar
+
+from glab_cli_extras.artifacts.job_logs import fetch_job_log, wants_log
+from glab_cli_extras.events import RawEvent
+from glab_cli_extras.gitlab import queries
+from glab_cli_extras.gitlab.client import ApiError, NotFound
+from glab_cli_extras.resources.base import Poller, gid_to_int, lower
+
+log = logging.getLogger(__name__)
+
+FINAL_JOB_STATUSES = frozenset({"success", "failed", "canceled", "skipped"})
+FINAL_PIPELINE_STATUSES = frozenset({"success", "failed", "canceled", "skipped"})
+QUEUED_PIPELINE_STATUSES = frozenset({"created", "pending", "waiting_for_resource", "preparing", "scheduled"})
+LOG_FETCH_DELAY = 5.0
+"""Wait after a job ends, so GitLab can archive the trace first."""
+LOG_FETCH_ATTEMPTS = 3
+
+INTERVAL_RUNNING = 5.0
+INTERVAL_QUEUED = 30.0
+INTERVAL_RUNNING_NO_ETAG = 15.0
+INTERVAL_QUEUED_NO_ETAG = 60.0
+
+
+@dataclass(frozen=True, slots=True)
+class JobState:
+    id: int
+    name: str
+    stage: str | None
+    status: str
+    allow_failure: bool
+    pipeline_id: int
+    project: str
+    started_at: str | None = None
+    finished_at: str | None = None
+    trace_size: int | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class DownstreamState:
+    id: int
+    iid: int | None
+    status: str
+    project: str
+    web_url: str | None = None
+
+
+@dataclass(frozen=True, slots=True)
+class PipelineSnapshot:
+    id: int
+    iid: int | None
+    project: str
+    status: str
+    ref: str | None
+    sha: str | None
+    web_url: str | None
+    jobs: tuple[JobState, ...] = ()
+    downstream: tuple[DownstreamState, ...] = ()
+
+
+def _web_url(host: str, path: Any) -> str | None:
+    return f"https://{host}{path}" if path else None
+
+
+def _trace_size(job: dict[str, Any]) -> int | None:
+    for artifact in (job.get("artifacts") or {}).get("nodes") or []:
+        if lower(artifact.get("fileType")) == "trace" and isinstance(artifact.get("size"), int):
+            return int(artifact["size"])
+    return None
+
+
+def _parse_jobs(nodes: list[Any], pipeline_id: int, project: str) -> list[JobState]:
+    jobs = []
+    for node in nodes:
+        jobs.append(
+            JobState(
+                id=gid_to_int(node["id"]),
+                name=str(node.get("name") or ""),
+                stage=(node.get("stage") or {}).get("name"),
+                status=lower(node.get("status")),
+                allow_failure=bool(node.get("allowFailure")),
+                pipeline_id=pipeline_id,
+                project=project,
+                started_at=node.get("startedAt"),
+                finished_at=node.get("finishedAt"),
+                trace_size=_trace_size(node),
+            )
+        )
+    return jobs
+
+
+def parse_pipeline(data: Any, host: str, project: str) -> PipelineSnapshot:
+    """Build a snapshot from the `PipelineTree` query result. Raises NotFound when the pipeline is missing."""
+    node = ((data or {}).get("project") or {}).get("pipeline")
+    if not node:
+        raise NotFound(f"pipeline not found in {project}", 404)
+    pipeline_id = gid_to_int(node["id"])
+    jobs = _parse_jobs((node.get("jobs") or {}).get("nodes") or [], pipeline_id, project)
+    downstream = []
+    for child in (node.get("downstream") or {}).get("nodes") or []:
+        child_id = gid_to_int(child["id"])
+        child_project = str((child.get("project") or {}).get("fullPath") or project)
+        downstream.append(
+            DownstreamState(
+                id=child_id,
+                iid=int(child["iid"]) if child.get("iid") else None,
+                status=lower(child.get("status")),
+                project=child_project,
+                web_url=_web_url(host, child.get("path")),
+            )
+        )
+        jobs.extend(_parse_jobs((child.get("jobs") or {}).get("nodes") or [], child_id, child_project))
+    return PipelineSnapshot(
+        id=pipeline_id,
+        iid=int(node["iid"]) if node.get("iid") else None,
+        project=project,
+        status=lower(node.get("status")),
+        ref=node.get("ref"),
+        sha=node.get("sha"),
+        web_url=_web_url(host, node.get("path")),
+        jobs=tuple(sorted(jobs, key=lambda j: j.id)),
+        downstream=tuple(sorted(downstream, key=lambda d: d.id)),
+    )
+
+
+def _job_data(job: JobState) -> dict[str, Any]:
+    data: dict[str, Any] = {
+        "pipeline_id": job.pipeline_id,
+        "job_id": job.id,
+        "name": job.name,
+        "stage": job.stage,
+        "status": job.status,
+    }
+    if job.allow_failure:
+        data["allow_failure"] = True
+    return data
+
+
+def diff_pipeline(prev: PipelineSnapshot, cur: PipelineSnapshot) -> list[RawEvent]:
+    """Events between two snapshots of one pipeline tree: job transitions first, then the pipeline's own status."""
+    events: list[RawEvent] = []
+    known_downstream = {d.id for d in prev.downstream}
+    for child in cur.downstream:
+        if child.id not in known_downstream:
+            events.append(
+                RawEvent(
+                    "downstream_created",
+                    {
+                        "pipeline_id": cur.id,
+                        "downstream_pipeline_id": child.id,
+                        "project": child.project,
+                        "status": child.status,
+                        "web_url": child.web_url,
+                    },
+                )
+            )
+    old_jobs = {j.id: j for j in prev.jobs}
+    for job in cur.jobs:
+        old = old_jobs.get(job.id)
+        old_status = old.status if old else None
+        if old_status == job.status:
+            continue
+        if job.status == "running" and old_status != "running":
+            events.append(RawEvent("job_started", _job_data(job)))
+        elif job.status in FINAL_JOB_STATUSES and job.status != "skipped" and old_status not in FINAL_JOB_STATUSES:
+            events.append(RawEvent("job_finished", _job_data(job)))
+    if prev.status != cur.status:
+        events.append(RawEvent("status_changed", {"pipeline_id": cur.id, "from": prev.status, "to": cur.status}))
+        if cur.status in FINAL_PIPELINE_STATUSES and prev.status not in FINAL_PIPELINE_STATUSES:
+            events.append(RawEvent("finished", {"pipeline_id": cur.id, "status": cur.status, "web_url": cur.web_url}))
+    return events
+
+
+@dataclass
+class _PendingLog:
+    job: JobState
+    event: RawEvent
+    due: float
+    attempts: int = 0
+
+
+@dataclass
+class _EtagState:
+    etag: str | None = None
+    supported: bool = True
+    pending_logs: dict[int, _PendingLog] = field(default_factory=dict)
+
+
+class PipelinePoller(Poller[PipelineSnapshot]):
+    kind: ClassVar = "pipeline"
+    snapshot_type: ClassVar = PipelineSnapshot
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        super().__init__(*args, **kwargs)
+        self._state = _EtagState()
+
+    @property
+    def pipeline_final(self) -> bool:
+        return self.snapshot is not None and self.snapshot.status in FINAL_PIPELINE_STATUSES
+
+    async def _fetch(self) -> PipelineSnapshot | None:
+        assert self.ref.id is not None
+        result = await self.ctx.client.graphql(
+            queries.load("pipeline"),
+            {"project": self.ref.project, "id": f"gid://gitlab/Ci::Pipeline/{self.ref.id}"},
+            etag_resource=f"pipelines/id/{self.ref.id}" if self._state.supported else None,
+            if_none_match=self._state.etag,
+            kind="pipeline",
+        )
+        if result.not_modified:
+            return None
+        if self._state.supported and not result.etag:
+            log.info("%s: no ETag from GitLab, falling back to plain polling", self.ref.key)
+            self._state.supported = False
+        self._state.etag = result.etag
+        return parse_pipeline(result.data, self.ref.host, self.ref.project)
+
+    async def poll(self) -> list[RawEvent]:
+        events: list[RawEvent] = []
+        if not self.pipeline_final or self.snapshot is None:
+            cur = await self._fetch()
+            if cur is not None:
+                prev = self.snapshot
+                self.snapshot = cur
+                if prev is not None:
+                    events.extend(self._hold_back_for_logs(diff_pipeline(prev, cur)))
+        events.extend(await self._fetch_due_logs())
+        if self.pipeline_final and not self._state.pending_logs and self.snapshot is not None:
+            self.terminal_reason = "finished"
+            self.terminal_data = {"status": self.snapshot.status}
+        return events
+
+    def _hold_back_for_logs(self, events: list[RawEvent]) -> list[RawEvent]:
+        if self.options.logs == "none" or self.snapshot is None:
+            return events
+        jobs = {j.id: j for j in self.snapshot.jobs}
+        released = []
+        now = self.ctx.clock()
+        for event in events:
+            job = jobs.get(int(event.data.get("job_id", 0))) if event.kind == "job_finished" else None
+            if job is not None and wants_log(self.options.logs, job.status):
+                self._state.pending_logs[job.id] = _PendingLog(job, event, now + LOG_FETCH_DELAY)
+            else:
+                released.append(event)
+        return released
+
+    async def _fetch_due_logs(self) -> list[RawEvent]:
+        now = self.ctx.clock()
+        released = []
+        for job_id, pending in sorted(self._state.pending_logs.items()):
+            if pending.due > now:
+                continue
+            pending.attempts += 1
+            try:
+                fetched = await fetch_job_log(
+                    self.ctx.client,
+                    self.ctx.cache_root,
+                    pending.job.project,
+                    pending.job.id,
+                    pending.job.name,
+                    pending.job.trace_size,
+                )
+            except (ApiError, OSError) as exc:
+                if pending.attempts < LOG_FETCH_ATTEMPTS:
+                    pending.due = now + LOG_FETCH_DELAY * pending.attempts
+                    continue
+                data = {**pending.event.data, "log_error": str(exc)}
+                released.append(replace(pending.event, data=data))
+            else:
+                data = {**pending.event.data, "log_truncated": fetched.truncated}
+                released.append(replace(pending.event, data=data, artifacts=(str(fetched.path),)))
+            del self._state.pending_logs[job_id]
+        return released
+
+    def next_delay(self) -> float:
+        if self._state.pending_logs:
+            now = self.ctx.clock()
+            soonest = min(p.due for p in self._state.pending_logs.values())
+            return max(0.5, min(soonest - now, INTERVAL_RUNNING))
+        queued = self.snapshot is not None and self.snapshot.status in QUEUED_PIPELINE_STATUSES
+        if self._state.supported:
+            return INTERVAL_QUEUED if queued else INTERVAL_RUNNING
+        return INTERVAL_QUEUED_NO_ETAG if queued else INTERVAL_RUNNING_NO_ETAG
+
+    def expected_cost(self) -> float:
+        # Most ETag probes are 304s, which the budget charges at 0.1.
+        return 0.3 if self._state.supported else 1.0
+
+    def summary(self) -> dict[str, Any]:
+        snap = self.snapshot
+        if snap is None:
+            return {}
+        counts: dict[str, int] = {}
+        for job in snap.jobs:
+            counts[job.status] = counts.get(job.status, 0) + 1
+        return {
+            "pipeline_id": snap.id,
+            "status": snap.status,
+            "ref": snap.ref,
+            "sha": snap.sha,
+            "web_url": snap.web_url,
+            "jobs": dict(sorted(counts.items())),
+            "downstream": [d.id for d in snap.downstream],
+            "failed_jobs": [j.name for j in snap.jobs if j.status == "failed" and not j.allow_failure],
+        }

glab_cli_extras/serde.py

@@ -0,0 +1,75 @@
+"""JSON conversion for the frozen snapshot dataclasses.
+
+Snapshots travel from the daemon to the client (which stores the last one in `state.json`) and back after a daemon
+restart, so the new daemon diffs against what the client saw last. Only the types snapshots use are supported:
+dataclasses, `tuple[X, ...]`, `dict[str, X]`, `X | None` and JSON scalars.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import hashlib
+import json
+import types
+import typing
+from typing import Any, TypeVar, get_args, get_origin, get_type_hints
+
+T = TypeVar("T")
+
+
+def to_jsonable(value: Any) -> Any:
+    if dataclasses.is_dataclass(value) and not isinstance(value, type):
+        return {f.name: to_jsonable(getattr(value, f.name)) for f in dataclasses.fields(value)}
+    if isinstance(value, list | tuple):
+        return [to_jsonable(item) for item in value]
+    if isinstance(value, dict):
+        return {str(k): to_jsonable(v) for k, v in value.items()}
+    return value
+
+
+def _convert(tp: Any, data: Any) -> Any:
+    if tp is Any:
+        return data
+    origin = get_origin(tp)
+    if origin in (typing.Union, types.UnionType):
+        options = [a for a in get_args(tp) if a is not type(None)]
+        if data is None:
+            return None
+        return _convert(options[0], data) if len(options) == 1 else data
+    if origin is tuple:
+        args = get_args(tp)
+        if not isinstance(data, list | tuple):
+            raise ValueError(f"expected a list for {tp}, got {type(data).__name__}")
+        if len(args) == 2 and args[1] is Ellipsis:
+            return tuple(_convert(args[0], item) for item in data)
+        return tuple(_convert(a, item) for a, item in zip(args, data, strict=True))
+    if origin is dict:
+        _, value_type = get_args(tp)
+        if not isinstance(data, dict):
+            raise ValueError(f"expected an object for {tp}")
+        return {str(k): _convert(value_type, v) for k, v in data.items()}
+    if isinstance(tp, type) and dataclasses.is_dataclass(tp):
+        if not isinstance(data, dict):
+            raise ValueError(f"expected an object for {tp.__name__}")
+        hints = get_type_hints(tp)
+        kwargs = {f.name: _convert(hints[f.name], data[f.name]) for f in dataclasses.fields(tp) if f.name in data}
+        return tp(**kwargs)
+    if tp is float and isinstance(data, int | float) and not isinstance(data, bool):
+        return float(data)
+    if tp in (int, str, bool, float) and not isinstance(data, tp):
+        raise ValueError(f"expected {tp.__name__}, got {type(data).__name__}")
+    return data
+
+
+def from_jsonable(cls: type[T], data: Any) -> T:
+    """Rebuild a dataclass from `to_jsonable` output. Raises ValueError on a shape mismatch."""
+    try:
+        result = _convert(cls, data)
+    except (KeyError, TypeError) as exc:
+        raise ValueError(f"cannot load {cls.__name__}: {exc}") from exc
+    return typing.cast(T, result)
+
+
+def stable_hash(value: Any) -> str:
+    canonical = json.dumps(to_jsonable(value), sort_keys=True, separators=(",", ":"), ensure_ascii=False)
+    return hashlib.sha256(canonical.encode("utf-8")).hexdigest()[:16]

glab_cli_extras/watch/changelog.py

@@ -0,0 +1,86 @@
+"""The client's per-resource changelog: `events.jsonl` (append-only) and `state.json` (the last snapshot).
+
+The stored snapshot lets a watcher resubscribe after a daemon restart without a fake "something changed": the new
+daemon diffs against it, and the client drops the new `watch_started` when the snapshot hash did not move.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from glab_cli_extras.events import Event, utc_now_iso
+from glab_cli_extras.gitlab.refs import ResourceRef
+from glab_cli_extras.paths import project_dir, sanitize_part
+
+
+def resource_dir_name(ref: ResourceRef) -> str:
+    if ref.kind in ("mr", "pipeline"):
+        return f"{ref.kind}-{ref.id}"
+    if ref.kind == "branch":
+        return f"branch-{sanitize_part(ref.branch or '')}"
+    return ref.kind
+
+
+@dataclass(frozen=True)
+class StoredState:
+    snapshot_hash: str | None
+    snapshot: Any
+
+
+class Changelog:
+    def __init__(self, root: Path, ref: ResourceRef) -> None:
+        self.ref = ref
+        self.dir = project_dir(root, ref.host, ref.project) / resource_dir_name(ref)
+        self.events_path = self.dir / "events.jsonl"
+        self.state_path = self.dir / "state.json"
+
+    def append(self, events: Iterable[Event]) -> None:
+        lines = [json.dumps(e.to_json(), ensure_ascii=False, separators=(",", ":")) + "\n" for e in events]
+        if not lines:
+            return
+        self.dir.mkdir(parents=True, exist_ok=True)
+        with open(self.events_path, "a", encoding="utf-8") as fh:
+            fh.writelines(lines)
+
+    def last_seq(self) -> int:
+        """The `seq` of the last event in events.jsonl, 0 when there is none."""
+        try:
+            with open(self.events_path, "rb") as fh:
+                fh.seek(0, os.SEEK_END)
+                size = fh.tell()
+                fh.seek(max(0, size - 256 * 1024))
+                tail = fh.read()
+        except OSError:
+            return 0
+        for line in reversed(tail.splitlines()):
+            try:
+                return int(json.loads(line)["seq"])
+            except (ValueError, KeyError, TypeError):
+                continue
+        return 0
+
+    def load_state(self) -> StoredState | None:
+        try:
+            raw = json.loads(self.state_path.read_text(encoding="utf-8"))
+        except (OSError, ValueError):
+            return None
+        if not isinstance(raw, dict) or raw.get("resource") != self.ref.key:
+            return None
+        return StoredState(raw.get("snapshot_hash"), raw.get("snapshot"))
+
+    def save_state(self, snapshot_hash: str, snapshot: Any) -> None:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        payload = {
+            "resource": self.ref.key,
+            "snapshot_hash": snapshot_hash,
+            "snapshot": snapshot,
+            "written_at": utc_now_iso(),
+        }
+        tmp = self.state_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        os.replace(tmp, self.state_path)

glab_cli_extras/watch/claude.py

@@ -0,0 +1,193 @@
+"""The `claude-message` stream: events go to the Claude Code session that started the watcher.
+
+The watcher finds its session through the cc-blackbox SDK and sends user messages over the session's messaging
+socket. Events received close together go out as one message: the first event of a burst waits up to 3 s for the
+rest. Each message is a `<glab-cli-extras-watcher>` block, because the receiver shows the content to the model but
+never the sender label. `seq` keeps every body unique, so the receiver's duplicate check never drops a real event.
+
+Delivery is best effort: the receiver may rate-limit a message, or hold it until its user approves it. The changelog
+always has every event.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from collections.abc import Callable
+from html import escape
+from pathlib import Path
+
+from cc_blackbox import (
+    ActiveSession,
+    ClaudeBlackboxError,
+    MessageTooLarge,
+    MessagingUnavailable,
+    Priority,
+    RateLimitedSender,
+    SessionGone,
+    UnsupportedProtocol,
+    current_session,
+)
+
+from glab_cli_extras.events import Event
+from glab_cli_extras.gitlab.refs import ResourceRef
+from glab_cli_extras.watch.sinks import StatusOutput, StdoutSink
+
+BURST_WAIT = 3.0
+MAX_CONTENT_BYTES = 64 * 1024
+LIVENESS_INTERVAL = 30.0
+FLUSH_TIMEOUT = 10.0
+
+
+def sender_name(ref: ResourceRef) -> str:
+    """The name Claude Code shows for the sender: `glab-watch mr group/project!123`."""
+    short = ref.short.split("/", 1)[1] if "/" in ref.short else ref.short
+    return f"glab-watch {ref.kind} {short}"
+
+
+def _event_line(event: Event) -> str:
+    payload: dict[str, object] = {"kind": event.kind, "seq": event.seq, "data": event.data}
+    if event.artifacts:
+        payload["artifacts"] = list(event.artifacts)
+    return json.dumps(payload, ensure_ascii=False, separators=(",", ":"))
+
+
+def format_message(ref: ResourceRef, events: list[Event], changelog: Path) -> str:
+    """One message for a batch of events. Above 64 KB the body becomes a count per kind; the changelog has it all."""
+    seqs = [e.seq for e in events]
+    seq = str(seqs[0]) if min(seqs) == max(seqs) else f"{min(seqs)}-{max(seqs)}"
+    head = f'<glab-cli-extras-watcher resource="{escape(ref.key)}" seq="{seq}" changelog="{escape(str(changelog))}">'
+    tail = "</glab-cli-extras-watcher>"
+    body = "\n".join(_event_line(e) for e in events)
+    content = f"{head}\n{body}\n{tail}"
+    if len(content.encode("utf-8")) <= MAX_CONTENT_BYTES:
+        return content
+    counts: dict[str, int] = {}
+    for event in events:
+        counts[event.kind] = counts.get(event.kind, 0) + 1
+    summary = json.dumps(
+        {"truncated": True, "events": len(events), "kinds": counts, "read": str(changelog)}, separators=(",", ":")
+    )
+    return f"{head}\n{summary}\n{tail}"
+
+
+class ClaudeMessageSink:
+    name = "claude-message"
+
+    def __init__(
+        self,
+        session: ActiveSession,
+        ref: ResourceRef,
+        changelog: Path,
+        priority: Priority,
+        status: StatusOutput,
+        *,
+        sender: RateLimitedSender | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        session_alive: Callable[[], bool] | None = None,
+    ) -> None:
+        if session.messaging_socket is None:
+            raise MessagingUnavailable("the session has messaging turned off")
+        self.session = session
+        self.ref = ref
+        self.changelog = changelog
+        self.priority = priority
+        self.status = status
+        self.envelope_name = sender_name(ref)
+        self.sender = sender or RateLimitedSender(
+            f"glab-watch:{os.getpid()}", sender_name=self.envelope_name, priority=priority
+        )
+        self._socket = session.messaging_socket
+        self._clock = clock
+        self._session_alive = session_alive or _session_still_current
+        self._buffer: list[Event] = []
+        self._deadline: float | None = None
+        self._gone = False
+        self._fallback: StdoutSink | None = None
+        self._last_liveness = clock()
+
+    def describe(self) -> str:
+        who = self.session.name or self.session.address
+        return (
+            f"claude-message to session {who!r} via {self._socket} "
+            f"(priority {self.priority}, sender {self.envelope_name!r})"
+        )
+
+    def emit(self, events: list[Event]) -> None:
+        if not events:
+            return
+        if self._fallback is not None:
+            self._fallback.emit(events)
+            return
+        self._buffer.extend(events)
+        if self._deadline is None:
+            self._deadline = self._clock() + BURST_WAIT
+        if any(e.kind == "watch_ended" for e in events):
+            self._send_buffer()
+
+    def seconds_until_flush(self) -> float | None:
+        if self._deadline is None:
+            return None
+        return max(0.0, self._deadline - self._clock())
+
+    def tick(self) -> None:
+        if self._deadline is not None and self._clock() >= self._deadline:
+            self._send_buffer()
+
+    def _send_buffer(self) -> None:
+        events, self._buffer, self._deadline = self._buffer, [], None
+        if not events or self._gone:
+            return
+        if self._fallback is not None:
+            self._fallback.emit(events)
+            return
+        content = format_message(self.ref, events, self.changelog)
+        try:
+            self.sender.send(self._socket, content)
+        except SessionGone:
+            self._gone = True
+        except (UnsupportedProtocol, MessagingUnavailable) as exc:
+            # The session stopped taking messages from us, for example after a Claude Code update changed the
+            # protocol. Keep the events flowing on stdout rather than dropping them.
+            self.status.line(f"stream fallback: cannot message the session ({exc}); events now go to stdout")
+            self._fallback = StdoutSink()
+            self._fallback.emit(events)
+        except (MessageTooLarge, ClaudeBlackboxError, OSError) as exc:
+            self.status.line(f"could not message the session: {exc}; the events are in {self.changelog}")
+
+    def alive(self) -> bool:
+        if self._gone:
+            return False
+        now = self._clock()
+        if now - self._last_liveness >= LIVENESS_INTERVAL:
+            self._last_liveness = now
+            if not self._session_alive():
+                self._gone = True
+        return not self._gone
+
+    def close(self) -> None:
+        self._send_buffer()
+        deadline = self._clock() + FLUSH_TIMEOUT
+        while not self._gone and self.sender.pending_count(self._socket) and self._clock() < deadline:
+            time.sleep(min(1.0, self.sender.seconds_until_next_token(self._socket) + 0.05))
+            try:
+                self.sender.flush()
+            except SessionGone:
+                self._gone = True
+            except (ClaudeBlackboxError, OSError) as exc:
+                self.status.line(f"could not message the session: {exc}")
+                return
+
+
+def _session_still_current() -> bool:
+    session = current_session()
+    return session is not None and session.can_receive_messages
+
+
+def find_session() -> ActiveSession | None:
+    """The Claude Code session this process runs under, or None."""
+    try:
+        return current_session()
+    except (ClaudeBlackboxError, OSError):
+        return None