littlebearapps
diff --git a/‎CHANGELOG.md‎
Lines changed: 17 additions & 0 deletions b/‎CHANGELOG.md‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎pyproject.toml‎
Lines changed: 1 addition & 1 deletion b/‎pyproject.toml‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎src/untether/runner.py‎
Lines changed: 106 additions & 4 deletions b/‎src/untether/runner.py‎
Lines changed: 106 additions & 4 deletions
@@ -1,5 +1,22 @@
 # changelog
 
+## v0.34.1 (2026-03-07)
+
+### fixes
+
+- session stall diagnostics: add `/proc` process diagnostics (CPU, RSS, TCP, FDs, children), progressive stall warnings, liveness watchdog, event timeline tracking, and session completion summary [#97](https://github.com/littlebearapps/untether/issues/97)
+  - new `utils/proc_diag.py` module: `collect_proc_diag()`, `format_diag()`, `is_cpu_active()`
+  - `JsonlStreamState` tracks `last_stdout_at`, `event_count`, `last_event_type`, `recent_events` ring buffer, `stderr_capture`
+  - PID auto-injected into `StartedEvent.meta` via base class (all engines)
+  - progressive `_stall_monitor`: repeating warnings every 3 min with fresh `/proc` snapshots and Telegram notifications
+  - liveness watchdog: detects alive-but-silent subprocesses after 10 min with diagnostics; optional auto-kill (off by default, triple safety gate)
+  - `session.summary` structured log on every session completion
+  - `[watchdog]` config section: `liveness_timeout`, `stall_auto_kill`, `stall_repeat_seconds`
+- stream threading broken: `_ResumeLineProxy` hides `current_stream` from `ProgressEdits`, causing `event_count=0` and `last_event_type=None` for all engines [#98](https://github.com/littlebearapps/untether/issues/98)
+  - add `current_stream` property to `_ResumeLineProxy` and `_PreludeRunner`
+  - set `self.current_stream = stream` in Claude's overridden `run_impl`
+  - use `stream.stderr_capture` instead of separate `stderr_lines` in Claude's `run_impl`
+
 ## v0.34.0 (2026-03-07)
 
 ### fixes
 
@@ -2,7 +2,7 @@
 name = "untether"
 authors = [{name = "Little Bear Apps", email = "hello@littlebearapps.com"}]
 maintainers = [{name = "Little Bear Apps", email = "hello@littlebearapps.com"}]
-version = "0.34.0"
+version = "0.34.1"
 keywords = ["telegram", "claude-code", "codex", "opencode", "pi", "gemini-cli", "amp", "ai-agents", "coding-assistant", "remote-control", "cli-bridge"]
 description = "Run AI coding agents from your phone. Bridges Claude Code, Codex, OpenCode, Pi, Gemini CLI, and Amp to Telegram with interactive permissions, voice input, cost tracking, and live progress."
 readme = {file = "README.md", content-type = "text/markdown"}
 
@@ -2,12 +2,15 @@
 
 from __future__ import annotations
 
+import contextlib
 import json
 import re
 import signal
 import subprocess
+import time
+from collections import deque
 from collections.abc import AsyncIterator, Callable
-from dataclasses import dataclass
+from dataclasses import dataclass, field, replace
 from typing import Any, Protocol, cast
 from weakref import WeakValueDictionary
 
@@ -192,9 +195,21 @@ class JsonlStreamState:
     did_emit_completed: bool = False
     ignored_after_completed: bool = False
     jsonl_seq: int = 0
+    # Activity tracking for stall diagnostics
+    last_stdout_at: float = 0.0
+    last_event_type: str | None = None
+    last_event_tool: str | None = None
+    event_count: int = 0
+    recent_events: deque[tuple[float, str]] = field(
+        default_factory=lambda: deque(maxlen=10)
+    )
+    stderr_capture: list[str] = field(default_factory=list)
 
 
 class JsonlSubprocessRunner(BaseRunner):
+    # Exposed for diagnostics — set during run_impl, cleared on exit
+    current_stream: JsonlStreamState | None = None
+
     def get_logger(self) -> Any:
         return getattr(self, "logger", get_logger(__name__))
 
@@ -600,6 +615,10 @@ def _handle_jsonl_line(
         line = raw_line.strip()
         if not line:
             return []
+        # Track raw I/O activity
+        now = time.monotonic()
+        stream.last_stdout_at = now
+        stream.event_count += 1
         stream.jsonl_seq += 1
         seq = stream.jsonl_seq
         events = self._decode_jsonl_events(
@@ -612,9 +631,37 @@ def _handle_jsonl_line(
             logger=logger,
             pid=pid,
         )
+        # Peek at raw JSON for event timeline (engine-agnostic)
+        try:
+            raw_dict = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            raw_dict = None
+        if isinstance(raw_dict, dict):
+            etype = str(raw_dict.get("type", "unknown"))
+            etool = None
+            # Cover common engine conventions for tool name
+            for key in ("tool_name", "tool", "name"):
+                val = raw_dict.get(key)
+                if isinstance(val, str) and val:
+                    etool = val
+                    break
+            # Also check nested item.type for Codex-style events
+            item = raw_dict.get("item")
+            if etool is None and isinstance(item, dict):
+                itype = item.get("type")
+                if isinstance(itype, str) and itype:
+                    etool = itype
+            stream.last_event_type = etype
+            stream.last_event_tool = etool
+            label = f"tool:{etool}" if etool else etype
+            stream.recent_events.append((now, label))
         output: list[UntetherEvent] = []
         for evt in events:
             if isinstance(evt, StartedEvent):
+                # Inject subprocess PID into meta for diagnostics
+                meta = dict(evt.meta) if evt.meta else {}
+                meta["pid"] = pid
+                evt = replace(evt, meta=meta)
                 stream.found_session, emit = self._process_started_event(
                     evt,
                     expected_session=stream.expected_session,
@@ -663,6 +710,10 @@ async def _iter_jsonl_events(
 
     _WATCHDOG_POLL_SECONDS: float = 0.5
 
+    _LIVENESS_TIMEOUT_SECONDS: float = 600.0
+
+    _stall_auto_kill: bool = False
+
     async def _subprocess_watchdog(
         self,
         proc: Any,
@@ -678,15 +729,66 @@ async def _subprocess_watchdog(
         process death (``proc.wait()`` blocks until pipes drain, so we use
         ``os.kill(pid, 0)``), then after a grace period kills the process group
         to terminate orphan children and unblock the readers.
+
+        Also detects liveness stalls: process alive but no stdout for
+        ``_LIVENESS_TIMEOUT_SECONDS``.
         """
         import os as _os
 
+        from .utils.proc_diag import collect_proc_diag, is_cpu_active
+
+        liveness_warned = False
+        prev_diag = None
+
         # Poll until the process is dead or the reader finishes.
         while not reader_done.is_set():
             try:
                 _os.kill(pid, 0)
             except (ProcessLookupError, PermissionError):
                 break  # process exited
+
+            # Liveness stall detection
+            if (
+                not liveness_warned
+                and stream.last_stdout_at > 0
+                and not stream.did_emit_completed
+            ):
+                idle = time.monotonic() - stream.last_stdout_at
+                if idle >= self._LIVENESS_TIMEOUT_SECONDS:
+                    liveness_warned = True
+                    diag = collect_proc_diag(pid)
+                    cpu_active = is_cpu_active(prev_diag, diag)
+                    recent = list(stream.recent_events)[-5:]
+                    logger.warning(
+                        "subprocess.liveness_stall",
+                        pid=pid,
+                        idle_seconds=round(idle, 1),
+                        event_count=stream.event_count,
+                        last_event_type=stream.last_event_type,
+                        tcp_established=diag.tcp_established if diag else None,
+                        rss_kb=diag.rss_kb if diag else None,
+                        cpu_active=cpu_active,
+                        recent_events=[(round(t, 1), lbl) for t, lbl in recent],
+                    )
+                    # Auto-kill: config enabled + zero TCP + CPU NOT active
+                    if (
+                        self._stall_auto_kill
+                        and diag is not None
+                        and diag.tcp_established == 0
+                        and diag.alive
+                        and cpu_active is not True
+                    ):
+                        logger.warning(
+                            "subprocess.liveness_kill",
+                            pid=pid,
+                            reason="zero_tcp_zero_cpu",
+                        )
+                        with contextlib.suppress(
+                            ProcessLookupError, PermissionError, OSError
+                        ):
+                            _os.killpg(pid, signal.SIGKILL)
+                    prev_diag = diag
+
             await anyio.sleep(self._WATCHDOG_POLL_SECONDS)
         if stream.did_emit_completed or reader_done.is_set():
             return
@@ -755,7 +857,7 @@ async def run_impl(
             await self._send_payload(proc, payload, logger=logger, resume=resume)
 
             stream = JsonlStreamState(expected_session=resume)
-            stderr_lines: list[str] = []
+            self.current_stream = stream
             reader_done = anyio.Event()
 
             async with anyio.create_task_group() as tg:
@@ -764,7 +866,7 @@ async def run_impl(
                     proc.stderr,
                     logger,
                     tag,
-                    stderr_lines,
+                    stream.stderr_capture,
                 )
                 tg.start_soon(
                     self._subprocess_watchdog,
@@ -796,7 +898,7 @@ async def run_impl(
                     resume=resume,
                     found_session=found_session,
                     state=state,
-                    stderr_lines=stderr_lines or None,
+                    stderr_lines=stream.stderr_capture or None,
                 )
                 for evt in events:
                     if isinstance(evt, CompletedEvent):