optio-claudecode 0.2.2__tar.gz → 0.2.4__tar.gz

{optio_claudecode-0.2.2 → optio_claudecode-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optio-claudecode
-Version: 0.2.2
+Version: 0.2.4
 Summary: Run Anthropic Claude Code as an optio task; local subprocess or remote via SSH; ttyd-served TUI iframe.
 Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
 License-Expression: Apache-2.0
@@ -24,6 +24,7 @@ Requires-Dist: optio-core<0.3,>=0.2
 Requires-Dist: optio-host<0.3,>=0.2
 Requires-Dist: optio-agents<0.3,>=0.2
 Requires-Dist: asyncssh>=2.14
+Requires-Dist: aiohttp>=3.9
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

{optio_claudecode-0.2.2 → optio_claudecode-0.2.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optio-claudecode"
-version = "0.2.2"
+version = "0.2.4"
 description = "Run Anthropic Claude Code as an optio task; local subprocess or remote via SSH; ttyd-served TUI iframe."
 readme = "README.md"
 license = "Apache-2.0"
@@ -30,6 +30,7 @@ dependencies = [
     "optio-host>=0.2,<0.3",
     "optio-agents>=0.2,<0.3",
     "asyncssh>=2.14",
+    "aiohttp>=3.9",
 ]
 
 [project.optional-dependencies]

{optio_claudecode-0.2.2 → optio_claudecode-0.2.4}/src/optio_claudecode/host_actions.py

@@ -676,18 +676,41 @@ def _claude_pgrep_pattern(claude_path: str) -> str:
     return "^" + body
 
 
+def _socket_pkill_pattern(socket_path: str) -> str:
+    """Anchored pkill -f pattern matching the orphan ttyd that carries
+    ``socket_path`` in its cmdline (``ttyd ... -- tmux -S <socket> attach``).
+
+    The ``ttyd`` binary token is bracket-escaped (``[t]tyd``) so pkill's own
+    argv does not self-match — same trick as ``_claude_pgrep_pattern``'s
+    ``[c]laude``. The full ``socket_path`` is kept verbatim so the match is
+    scoped to this task's private socket (and not some other ttyd)."""
+    if not socket_path:
+        return socket_path
+    return f"[t]tyd.*{socket_path}"
+
+
+async def _kill_ttyd_by_socket(host: "Host", socket_path: str) -> None:
+    """Reap a detached orphan ttyd that has no tracked launch handle.
+
+    Normal teardown kills ttyd via ``terminate_subprocess(launched_handle)``.
+    A crash orphan's ttyd is re-parented to init with no handle, so it is
+    reaped host-side by an anchored ``pkill -f`` on the private socket path it
+    carries in its cmdline. Best-effort: pkill exits non-zero when nothing
+    matches."""
+    pattern = _socket_pkill_pattern(socket_path)
+    await host.run_command(f"pkill -KILL -f {shlex.quote(pattern)} || true")
+
+
 async def kill_claude_processes(
     host: "Host", claude_path: str, *, signal: str = "KILL",
 ) -> None:
-    """Force the per-task claude process tree to exit.
-
-    Teardown SIGKILLs ttyd and kill-sessions tmux, but claude runs under pasta
-    in its own process group and ignores the tmux pane's SIGHUP, so it is
-    orphaned and survives — ``await_claude_gone`` then waits for a process
-    nothing kills, blowing the cancel grace. pasta isolates only the network
-    namespace (not PID), so a host-side ``pkill`` on the anchored argv[0] path
-    reaches it. Best-effort: pkill exits non-zero when nothing matches.
-    """
+    """Kill the per-task claude via an anchored host-side ``pkill``.
+
+    claude ignores the tmux pane SIGHUP, and MAY run under a pasta netns
+    wrapper (only when ``OPTIO_CLAUDECODE_NETNS`` is set AND the host is
+    local). The anchored pkill on claude's argv[0] reaches it regardless of
+    whether pasta wraps it, because pasta isolates the network namespace, not
+    PID. Best-effort: pkill exits non-zero when nothing matches."""
     pattern = _claude_pgrep_pattern(claude_path)
     await host.run_command(f"pkill -{signal} -f {shlex.quote(pattern)} || true")
 
@@ -721,6 +744,58 @@ async def await_claude_gone(
         waited += poll_s
 
 
+async def teardown_session_tree(
+    host: "Host",
+    *,
+    tmux_path: str,
+    tmux_socket: str,
+    tmux_session: str,
+    claude_path: str,
+    ttyd_handle: "ProcessHandle | None" = None,
+    aggressive: bool,
+) -> None:
+    """Kill a full claudecode session tree (ttyd + tmux + claude), reused by
+    both normal teardown and crash-orphan rescue.
+
+    Four best-effort steps, each isolated so one failure does not abort the
+    rest:
+      1. ttyd — via the tracked launch handle (normal teardown) or, when no
+         handle exists (a crash orphan re-parented to init), an anchored
+         host-side pkill on the socket path.
+      2. ``kill-session`` — SIGHUPs the tmux pane.
+      3. ``kill_claude_processes`` — claude ignores the pane SIGHUP (and may
+         run under a pasta netns wrapper), so it is killed explicitly via an
+         anchored host-side pkill on its argv[0]; this reaches it whether or
+         not pasta wraps it (pasta isolates the network namespace, not PID).
+      4. ``await_claude_gone`` — waits for quiescence so a subsequent capture
+         tar does not race a dying claude."""
+    if ttyd_handle is not None:
+        try:
+            await host.terminate_subprocess(ttyd_handle, aggressive=aggressive)
+        except Exception:
+            _LOG.exception("terminate_subprocess (ttyd) failed")
+    else:
+        try:
+            await _kill_ttyd_by_socket(host, tmux_socket)
+        except Exception:
+            _LOG.exception("orphan ttyd reap failed (socket=%s)", tmux_socket)
+
+    try:
+        await _kill_tmux_session(host, tmux_path, tmux_socket, tmux_session)
+    except Exception:
+        _LOG.exception("tmux session teardown failed")
+
+    try:
+        await kill_claude_processes(host, claude_path)
+    except Exception:
+        _LOG.exception("kill_claude_processes failed")
+
+    try:
+        await await_claude_gone(host, claude_path)
+    except Exception:
+        _LOG.exception("await_claude_gone failed; proceeding")
+
+
 async def tmux_session_alive(
     host: "Host", tmux_path: str, socket_path: str, session_name: str,
 ) -> bool:

optio_claudecode-0.2.4/src/optio_claudecode/input_listener.py

@@ -0,0 +1,64 @@
+"""In-session HTTP listener that receives human-typed messages and a small
+lock helper that serializes them against system-message injection.
+
+The listener runs INSIDE the session's asyncio loop (engine-side), so its
+handler natively holds the session's injector and lock — no registry, no RPC,
+no Mongo poll. It is reached through the API widget proxy exactly as ttyd is
+(registered as controlUpstream). See
+docs/2026-06-08-claudecode-input-channel-design.md.
+"""
+from __future__ import annotations
+
+import asyncio
+from typing import Awaitable, Callable
+
+from aiohttp import web
+
+
+def serialized(
+    lock: asyncio.Lock, send: Callable[[str], Awaitable[None]],
+) -> Callable[[str], Awaitable[None]]:
+    """Wrap `send` so every call holds `lock` for the whole injection burst.
+    Both the system path (_agent_sender) and the human path go through one
+    such wrapper sharing one lock → bursts never interleave."""
+    async def _send(text: str) -> None:
+        async with lock:
+            await send(text)
+    return _send
+
+
+async def start_input_listener(
+    *,
+    bind_iface: str,
+    on_input: Callable[[str], Awaitable[None]],
+) -> tuple[web.AppRunner, int]:
+    """Start a one-route aiohttp app: POST /input {text} -> on_input(text).
+
+    Returns (runner, port). Bind on port 0 (OS-assigned); the actual port is
+    read back from the bound socket. on_input raises on injection failure;
+    that becomes a 502 {ok:false, reason:"send-failed"}.
+    """
+    async def handle(request: web.Request) -> web.Response:
+        try:
+            payload = await request.json()
+        except Exception:
+            return web.json_response({"ok": False, "reason": "bad-json"}, status=400)
+        text = payload.get("text")
+        if not isinstance(text, str) or not text:
+            return web.json_response({"ok": False, "reason": "bad-text"}, status=400)
+        try:
+            await on_input(text)
+        except Exception:
+            return web.json_response({"ok": False, "reason": "send-failed"}, status=502)
+        return web.json_response({"ok": True})
+
+    app = web.Application()
+    app.router.add_post("/input", handle)
+    runner = web.AppRunner(app)
+    await runner.setup()
+    site = web.TCPSite(runner, bind_iface, 0)
+    await site.start()
+    # Read the OS-assigned port back from the bound server socket.
+    server = site._server  # aiohttp exposes the asyncio.Server here
+    port = server.sockets[0].getsockname()[1]
+    return runner, port

{optio_claudecode-0.2.2 → optio_claudecode-0.2.4}/src/optio_claudecode/session.py

@@ -33,6 +33,7 @@ from optio_agents import get_protocol
 
 from optio_claudecode import cred_watcher
 from optio_claudecode import host_actions
+from optio_claudecode.input_listener import serialized, start_input_listener
 from optio_claudecode.account import resolve_account_summary
 from optio_claudecode.oauth_redirect import rewrite_oauth_redirect
 from optio_claudecode.seed_manifest import (
@@ -93,6 +94,8 @@ async def run_claudecode_session(
     tmux_path: str | None = None
     tmux_socket: str | None = None
     tmux_session: str | None = None
+    injection_lock = asyncio.Lock()
+    input_runner = None  # aiohttp AppRunner | None
     cancelled = False
     # Set by _prepare (the driver runs it after the workdir wipe, before the
     # optio.log tail); read by the body and the teardown finally.
@@ -110,6 +113,11 @@ async def run_claudecode_session(
 
     await host.connect()
 
+    # Crash-orphan rescue: if a non-graceful host death left this task's
+    # tmux/ttyd/claude tree running with unsaved state, harvest it into a fresh
+    # snapshot and kill it BEFORE the driver wipes the workdir. No-op otherwise.
+    await _rescue_orphan_if_present(ctx, config=config, host=host)
+
     async def _prepare(host: Host, hook_ctx: HookContext) -> None:
         """Install the claude+ttyd runtime and restore a resume snapshot.
 
@@ -176,7 +184,7 @@ async def run_claudecode_session(
                 )
 
     async def _claudecode_body(host: Host, hook_ctx: HookContext) -> None:
-        nonlocal launched_handle, tmux_path, tmux_socket, tmux_session
+        nonlocal launched_handle, tmux_path, tmux_socket, tmux_session, input_runner
         nonlocal cred_baseline, cred_watch_task
         nonlocal resolved_seed_id, lease_holder
 
@@ -303,6 +311,18 @@ async def run_claudecode_session(
         await ctx.set_widget_data({
             "iframeSrc": "{widgetProxyUrl}/",
         })
+        # In-session input listener: receives human messages from the
+        # iframe-input widget via the API widget-control proxy and injects
+        # them under the same lock as system messages (no garbling).
+        async def _inject_raw(text: str) -> None:
+            await host_actions.send_text_to_claude(
+                host, tmux_path, tmux_socket, tmux_session, text,
+            )
+        input_runner, input_port = await start_input_listener(
+            bind_iface=ttyd_iface,
+            on_input=serialized(injection_lock, _inject_raw),
+        )
+        await ctx.set_control_upstream(f"http://{upstream_host}:{input_port}")
         ctx.report_progress(None, "Claude Code is live")
 
         # Await the claude process inside tmux (NOT the ttyd connection). ttyd
@@ -334,12 +354,12 @@ async def run_claudecode_session(
             cred_watch_task = None
 
     async def _agent_sender(message: str) -> None:
-        # tmux_* are set by _claudecode_body at launch; host is the session's
-        # Host. send_text_to_claude raises on a tmux failure, which
-        # send_to_agent converts to False.
-        await host_actions.send_text_to_claude(
-            host, tmux_path, tmux_socket, tmux_session, message,
-        )
+        # Serialized against the human-input listener via injection_lock so a
+        # system message can never interleave with a human burst.
+        async with injection_lock:
+            await host_actions.send_text_to_claude(
+                host, tmux_path, tmux_socket, tmux_session, message,
+            )
 
     try:
         await run_log_protocol_session(
@@ -358,41 +378,37 @@ async def run_claudecode_session(
         if not ctx.should_continue():
             cancelled = True
         _trace("finally: ENTER cancelled=%s resuming=%s", cancelled, resuming)
-        if launched_handle is not None:
-            _trace("finally: terminate_subprocess START aggressive=%s", cancelled)
-            try:
-                await host.terminate_subprocess(launched_handle, aggressive=cancelled)
-            except Exception:
-                _LOG.exception("terminate_subprocess failed")
-            _trace("finally: terminate_subprocess DONE")
-
-        if tmux_path is not None and tmux_socket is not None and tmux_session is not None:
+        if (
+            launched_handle is not None
+            and tmux_path is not None
+            and tmux_socket is not None
+            and tmux_session is not None
+            and claude_path
+        ):
+            _trace("finally: teardown_session_tree START aggressive=%s", cancelled)
             try:
-                await host_actions._kill_tmux_session(
-                    host, tmux_path, tmux_socket, tmux_session,
+                await host_actions.teardown_session_tree(
+                    host,
+                    tmux_path=tmux_path,
+                    tmux_socket=tmux_socket,
+                    tmux_session=tmux_session,
+                    claude_path=claude_path,
+                    ttyd_handle=launched_handle,
+                    aggressive=cancelled,
                 )
             except Exception:
-                _LOG.exception("tmux session teardown failed")
-
-        # Wait for claude to fully exit before snapshotting, so the tar of
-        # home/.claude reads a quiescent tree. kill-session only SIGHUPs
-        # claude and returns; claude may still be flushing settings / mcp-cache
-        # / locks as it dies, which would make the capture tar fail with
-        # "file changed as we read it". Best-effort + bounded; the strict tar
-        # exit check in _archive_home_claude is the backstop.
-        if launched_handle is not None and claude_path:
-            # claude runs under pasta in its own process group and ignores the
-            # tmux pane's SIGHUP from kill-session, so it is orphaned by the
-            # ttyd/tmux teardown above. Kill it explicitly, else await_claude_gone
-            # waits on a process nothing kills and the cancel grace is exceeded.
+                _LOG.exception("teardown_session_tree failed")
+            _trace("finally: teardown_session_tree DONE")
+
+        if input_runner is not None:
             try:
-                await host_actions.kill_claude_processes(host, claude_path)
+                await input_runner.cleanup()
             except Exception:
-                _LOG.exception("kill_claude_processes failed")
+                _LOG.exception("input listener cleanup failed")
             try:
-                await host_actions.await_claude_gone(host, claude_path)
+                await ctx.clear_control_upstream()
             except Exception:
-                _LOG.exception("await_claude_gone failed; proceeding to capture")
+                _LOG.exception("clear control upstream failed")
 
         if cred_watch_task is not None:
             cred_watch_task.cancel()
@@ -566,6 +582,89 @@ async def _extract_home_claude(host: Host, plain: bytes) -> None:
         await host.run_command(f"rm -f {shlex.quote(tmpfile)}")
 
 
+_RESCUE_MARKER = ".optio-rescue-pending"
+
+
+def _claude_bin_path(host: "Host") -> str:
+    """Deterministic launch path of claude inside the isolated HOME."""
+    return f"{host.workdir.rstrip('/')}/home/.local/bin/claude"
+
+
+async def _marker_present(host: "Host", marker_path: str) -> bool:
+    r = await host.run_command(
+        f"test -e {shlex.quote(marker_path)} && echo YES || true"
+    )
+    return "YES" in r.stdout
+
+
+async def _rescue_orphan_if_present(
+    ctx: ProcessContext, host: Host, config: ClaudeCodeTaskConfig,
+) -> None:
+    """Before the driver wipes the workdir, recover a crash-surviving orphan.
+
+    A non-graceful host death (disk-full, OOM, power loss) leaves the
+    tmux/ttyd/claude sub-tree running, re-parented to init, with unsaved state
+    on disk — but no snapshot. This bracket, run before
+    ``run_log_protocol_session`` (hence before ``setup_workdir``), detects that
+    orphan on the deterministic per-task socket, kills it, and captures its
+    live state into a fresh snapshot that the unchanged resume path then
+    restores. No-op unless an orphan (or a leftover rescue marker) is found.
+
+    Kill-before-capture is deliberate: a dead, static workdir prevents a live
+    claude from repopulating ``home/.claude`` into the plaintext workdir blob
+    after the expunge, and yields a race-free tar. See spec decisions D3/D4."""
+    if not getattr(config, "supports_resume", True):
+        return
+    if not bool(getattr(ctx, "resume", False)):
+        return
+
+    socket = host_actions._tmux_socket_path(host)
+    session = "optio"
+    marker_path = f"{host.workdir.rstrip('/')}/{_RESCUE_MARKER}"
+
+    tmux_path = await host_actions._require_tmux(host)
+    alive = await host_actions.tmux_session_alive(
+        host, tmux_path, socket, session,
+    )
+    if not alive and not await _marker_present(host, marker_path):
+        return  # normal resume; nothing to rescue
+
+    _LOG.warning(
+        "crash-orphan rescue: live=%s socket=%s — capturing live state before wipe",
+        alive, socket,
+    )
+
+    # 1. Durable marker (retry guard: kill removes the has-session signal).
+    await host.write_text(_RESCUE_MARKER, "")
+
+    # 2. Kill the orphan tree (handle-less: orphan ttyd reaped by socket).
+    claude_path = _claude_bin_path(host)
+    await host_actions.teardown_session_tree(
+        host,
+        tmux_path=tmux_path,
+        tmux_socket=socket,
+        tmux_session=session,
+        claude_path=claude_path,
+        ttyd_handle=None,
+        aggressive=True,
+    )
+
+    # 3. Capture the now-static workdir — identical artifacts to a normal
+    #    teardown capture. Exclude the marker so a restored workdir cannot
+    #    re-trigger rescue in a loop.
+    exclude = [*(config.workdir_exclude or []), _RESCUE_MARKER]
+    await _capture_snapshot(
+        ctx, host,
+        end_state="rescued",
+        workdir_exclude=exclude,
+        session_blob_encrypt=config.session_blob_encrypt,
+    )
+
+    # 4. Capture durable — clear the marker.
+    await host.run_command(f"rm -f {shlex.quote(marker_path)}")
+    _LOG.warning("crash-orphan rescue: fresh snapshot captured; orphan killed")
+
+
 async def _capture_snapshot(
     ctx: ProcessContext,
     host: Host,
@@ -783,7 +882,7 @@ def create_claudecode_task(
         process_id=process_id,
         name=name,
         description=description,
-        ui_widget="iframe",
+        ui_widget="iframe-input",
         supports_resume=config.supports_resume,
         metadata=metadata or {},
     )

{optio_claudecode-0.2.2 → optio_claudecode-0.2.4}/src/optio_claudecode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optio-claudecode
-Version: 0.2.2
+Version: 0.2.4
 Summary: Run Anthropic Claude Code as an optio task; local subprocess or remote via SSH; ttyd-served TUI iframe.
 Author-email: Kristof Csillag <kristof.csillag@deai-labs.com>
 License-Expression: Apache-2.0
@@ -24,6 +24,7 @@ Requires-Dist: optio-core<0.3,>=0.2
 Requires-Dist: optio-host<0.3,>=0.2
 Requires-Dist: optio-agents<0.3,>=0.2
 Requires-Dist: asyncssh>=2.14
+Requires-Dist: aiohttp>=3.9
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

{optio_claudecode-0.2.2 → optio_claudecode-0.2.4}/src/optio_claudecode.egg-info/SOURCES.txt

@@ -4,6 +4,7 @@ src/optio_claudecode/__init__.py
 src/optio_claudecode/account.py
 src/optio_claudecode/cred_watcher.py
 src/optio_claudecode/host_actions.py
+src/optio_claudecode/input_listener.py
 src/optio_claudecode/oauth.py
 src/optio_claudecode/oauth_redirect.py
 src/optio_claudecode/prompt.py
@@ -22,6 +23,9 @@ tests/test_await_claude_gone.py
 tests/test_cred_watcher.py
 tests/test_home_isolation.py
 tests/test_host_actions.py
+tests/test_injection_serialize.py
+tests/test_input_listener.py
+tests/test_kill_ttyd_by_socket.py
 tests/test_launch_detached_checked.py
 tests/test_oauth.py
 tests/test_oauth_redirect.py
@@ -29,6 +33,7 @@ tests/test_on_resume_refresh.py
 tests/test_prompt.py
 tests/test_purge_seed.py
 tests/test_rekey_projects.py
+tests/test_rescue_orphan.py
 tests/test_resume_prompt.py
 tests/test_resume_sentence_claudecode.py
 tests/test_runtime_cache.py
@@ -46,6 +51,7 @@ tests/test_session_seed_consume.py
 tests/test_session_seed_saveback.py
 tests/test_session_seed_unknown_id.py
 tests/test_snapshots.py
+tests/test_teardown_session_tree.py
 tests/test_tmux_persistence.py
 tests/test_tmux_socket_path.py
 tests/test_types.py

{optio_claudecode-0.2.2 → optio_claudecode-0.2.4}/src/optio_claudecode.egg-info/requires.txt

@@ -2,6 +2,7 @@ optio-core<0.3,>=0.2
 optio-host<0.3,>=0.2
 optio-agents<0.3,>=0.2
 asyncssh>=2.14
+aiohttp>=3.9
 
 [dev]
 pytest>=8.0

optio_claudecode-0.2.4/tests/test_injection_serialize.py

@@ -0,0 +1,21 @@
+"""serialized() prevents two injection bursts from overlapping."""
+import asyncio
+
+from optio_claudecode.input_listener import serialized
+
+
+async def test_serialized_no_interleave():
+    lock = asyncio.Lock()
+    active = 0
+    max_active = 0
+
+    async def raw_send(text):
+        nonlocal active, max_active
+        active += 1
+        max_active = max(max_active, active)
+        await asyncio.sleep(0.02)  # force overlap if unlocked
+        active -= 1
+
+    send = serialized(lock, raw_send)
+    await asyncio.gather(*(send(f"m{i}") for i in range(5)))
+    assert max_active == 1  # never two bursts at once

optio_claudecode-0.2.4/tests/test_input_listener.py

@@ -0,0 +1,49 @@
+"""POST /input delivers to on_input and maps results to acks."""
+import aiohttp
+
+from optio_claudecode.input_listener import start_input_listener
+
+
+async def _post(port, payload):
+    async with aiohttp.ClientSession() as s:
+        async with s.post(f"http://127.0.0.1:{port}/input", json=payload) as r:
+            return r.status, await r.json()
+
+
+async def test_listener_delivers_text_and_acks_ok():
+    seen = []
+
+    async def on_input(text):
+        seen.append(text)
+
+    runner, port = await start_input_listener(bind_iface="127.0.0.1", on_input=on_input)
+    try:
+        status, body = await _post(port, {"text": "hello world"})
+        assert status == 200 and body == {"ok": True}
+        assert seen == ["hello world"]
+    finally:
+        await runner.cleanup()
+
+
+async def test_listener_502_on_injection_failure():
+    async def on_input(text):
+        raise RuntimeError("tmux boom")
+
+    runner, port = await start_input_listener(bind_iface="127.0.0.1", on_input=on_input)
+    try:
+        status, body = await _post(port, {"text": "x"})
+        assert status == 502 and body["reason"] == "send-failed"
+    finally:
+        await runner.cleanup()
+
+
+async def test_listener_400_on_empty_text():
+    async def on_input(text):
+        pass
+
+    runner, port = await start_input_listener(bind_iface="127.0.0.1", on_input=on_input)
+    try:
+        status, _ = await _post(port, {"text": ""})
+        assert status == 400
+    finally:
+        await runner.cleanup()

optio_claudecode-0.2.4/tests/test_kill_ttyd_by_socket.py

@@ -0,0 +1,45 @@
+import pytest
+
+import optio_claudecode.host_actions as H
+
+
+class _Result:
+    def __init__(self, stdout=""):
+        self.stdout = stdout
+        self.stderr = ""
+        self.exit_code = 0
+
+
+class _Host:
+    def __init__(self):
+        self.commands = []
+
+    async def run_command(self, cmd, **kwargs):
+        self.commands.append(cmd)
+        return _Result()
+
+
+@pytest.mark.asyncio
+async def test_kill_ttyd_by_socket_anchored_pkill():
+    host = _Host()
+    await H._kill_ttyd_by_socket(host, "/tmp/optio-cc-deadbeef0badcafe.sock")
+    assert len(host.commands) == 1
+    cmd = host.commands[0]
+    # Targets ttyd processes by the socket path they carry in their cmdline.
+    assert "pkill" in cmd
+    assert "/tmp/optio-cc-deadbeef0badcafe.sock" in cmd
+    # Anchored so the rescue's own command line is not matched (mirrors the
+    # [c]laude self-match guard used for claude).
+    assert "optio-cc-deadbeef0badcafe.sock" in cmd
+    # Best-effort: never fails the caller when nothing matches.
+    assert "|| true" in cmd
+
+
+@pytest.mark.asyncio
+async def test_kill_ttyd_by_socket_does_not_self_match():
+    # The emitted pattern must contain a bracket-escape so pkill -f does not
+    # match its own argv. We assert the socket digest is bracket-split.
+    host = _Host()
+    await H._kill_ttyd_by_socket(host, "/tmp/optio-cc-abc123.sock")
+    cmd = host.commands[0]
+    assert "[" in cmd and "]" in cmd

optio_claudecode-0.2.4/tests/test_rescue_orphan.py

@@ -0,0 +1,270 @@
+import pytest
+
+import optio_claudecode.session as S
+
+
+class _Result:
+    def __init__(self, stdout=""):
+        self.stdout = stdout
+        self.stderr = ""
+        self.exit_code = 0
+
+
+class _Host:
+    """Stub host. ``existing`` is a set of marker paths reported present."""
+
+    def __init__(self, workdir, existing=None):
+        self.workdir = workdir
+        self.existing = set(existing or ())
+        self.written = []
+        self.removed = []
+        self.commands = []
+
+    async def run_command(self, cmd, **kwargs):
+        self.commands.append(cmd)
+        # Emulate `test -e <path> && echo YES || true` marker probes.
+        if cmd.startswith("test -e "):
+            path = cmd.split("test -e ", 1)[1].split(" ", 1)[0].strip("'\"")
+            return _Result("YES\n" if path in self.existing else "")
+        if cmd.startswith("rm -f "):
+            path = cmd.split("rm -f ", 1)[1].strip().strip("'\"")
+            self.removed.append(path)
+            self.existing.discard(path)
+        return _Result()
+
+    async def write_text(self, rel, text):
+        self.written.append(rel)
+        self.existing.add(f"{self.workdir.rstrip('/')}/{rel}")
+
+
+class _Config:
+    workdir_exclude = None
+    session_blob_encrypt = None
+
+
+class _Ctx:
+    process_id = "pid-1"
+    resume = True
+
+
+@pytest.fixture
+def patched(monkeypatch):
+    rec = {"alive": False, "teardown": [], "capture": [], "fail_capture": False}
+
+    async def _alive(host, tmux_path, socket, session):
+        return rec["alive"]
+
+    async def _require_tmux(host):
+        return "tmux"
+
+    def _socket(host):
+        return "/tmp/optio-cc-deadbeef.sock"
+
+    async def _teardown(host, **kw):
+        rec["teardown"].append(kw)
+
+    async def _capture(ctx, host, **kw):
+        rec["capture"].append(kw)
+        if rec["fail_capture"]:
+            raise RuntimeError("capture failed")
+
+    monkeypatch.setattr(S.host_actions, "tmux_session_alive", _alive)
+    monkeypatch.setattr(S.host_actions, "_require_tmux", _require_tmux)
+    monkeypatch.setattr(S.host_actions, "_tmux_socket_path", _socket)
+    monkeypatch.setattr(S.host_actions, "teardown_session_tree", _teardown)
+    monkeypatch.setattr(S, "_capture_snapshot", _capture)
+    return rec
+
+
+@pytest.mark.asyncio
+async def test_noop_when_no_session_and_no_marker(patched, tmp_path):
+    patched["alive"] = False
+    host = _Host(str(tmp_path))
+    await S._rescue_orphan_if_present(_Ctx(), host, _Config())
+    assert patched["teardown"] == []
+    assert patched["capture"] == []
+    assert host.written == []
+
+
+@pytest.mark.asyncio
+async def test_triggers_on_live_session_kill_before_capture(patched, tmp_path):
+    patched["alive"] = True
+    host = _Host(str(tmp_path))
+    await S._rescue_orphan_if_present(_Ctx(), host, _Config())
+    # Marker written, orphan killed, then captured — kill strictly before capture.
+    assert host.written == [".optio-rescue-pending"]
+    assert len(patched["teardown"]) == 1
+    assert patched["teardown"][0]["ttyd_handle"] is None
+    assert len(patched["capture"]) == 1
+    # end_state marks the rescue for forensics.
+    assert patched["capture"][0]["end_state"] == "rescued"
+    # Marker excluded from the snapshot so a restored workdir does not loop.
+    assert ".optio-rescue-pending" in (patched["capture"][0]["workdir_exclude"] or [])
+    # Marker cleared after capture success.
+    marker = f"{str(tmp_path).rstrip('/')}/.optio-rescue-pending"
+    assert marker in host.removed
+
+
+@pytest.mark.asyncio
+async def test_triggers_on_marker_even_without_session(patched, tmp_path):
+    patched["alive"] = False
+    marker = f"{str(tmp_path).rstrip('/')}/.optio-rescue-pending"
+    host = _Host(str(tmp_path), existing={marker})
+    await S._rescue_orphan_if_present(_Ctx(), host, _Config())
+    # Detect-by-marker path still rescues (mid-rescue retry).
+    assert len(patched["teardown"]) == 1
+    assert len(patched["capture"]) == 1
+
+
+@pytest.mark.asyncio
+async def test_capture_failure_persists_marker_and_reraises(patched, tmp_path):
+    patched["alive"] = True
+    patched["fail_capture"] = True
+    host = _Host(str(tmp_path))
+    with pytest.raises(RuntimeError):
+        await S._rescue_orphan_if_present(_Ctx(), host, _Config())
+    marker = f"{str(tmp_path).rstrip('/')}/.optio-rescue-pending"
+    # Marker NOT removed — a retried resume re-enters rescue.
+    assert marker not in host.removed
+
+
+@pytest.mark.asyncio
+async def test_skipped_when_not_resuming(patched, tmp_path):
+    patched["alive"] = True
+
+    class _FreshCtx:
+        process_id = "pid-1"
+        resume = False
+
+    host = _Host(str(tmp_path))
+    await S._rescue_orphan_if_present(_FreshCtx(), host, _Config())
+    assert patched["teardown"] == []
+    assert patched["capture"] == []
+
+
+# --------------------------------------------------------------------------
+# Integration: real (shim) detached session -> orphan -> rescue.
+#
+# Exercises the REAL teardown_session_tree + _capture_snapshot against a real
+# local tmux tree: launch a detached tmux session whose "claude" is a long-lived
+# sleep shim at the deterministic <workdir>/home/.local/bin/claude path, abandon
+# it (no teardown) so it is the orphan, then run _rescue_orphan_if_present and
+# assert the orphan is gone, a fresh "rescued" snapshot exists, and the marker is
+# cleared. Mirrors the launch scaffolding in test_tmux_persistence.py.
+# --------------------------------------------------------------------------
+
+import os  # noqa: E402
+import shutil  # noqa: E402
+
+from optio_claudecode import ClaudeCodeTaskConfig  # noqa: E402
+from optio_claudecode import host_actions as H  # noqa: E402
+
+
+_NO_TMUX = shutil.which("tmux") is None
+
+
+async def _launch_orphan_session(host):
+    """Start a detached tmux session whose 'claude' records its pid then sleeps,
+    on the deterministic per-task socket the rescue probes. Returns
+    (tmux_path, socket)."""
+    workdir = host.workdir
+    os.makedirs(f"{workdir}/home/.local/bin", exist_ok=True)
+    claude = f"{workdir}/home/.local/bin/claude"
+    marker = f"{workdir}/claude.pid"
+    with open(claude, "w") as f:
+        f.write(f"#!/bin/bash\necho $$ > {marker}\nexec sleep 60\n")
+    os.chmod(claude, 0o755)
+
+    # Plant credentials so the capture credentials-present guard passes.
+    os.makedirs(f"{workdir}/home/.claude", exist_ok=True)
+    with open(f"{workdir}/home/.claude/.credentials.json", "w") as f:
+        f.write('{"token": "test"}')
+
+    tmux_path = await H._require_tmux(host)
+    socket = H._tmux_socket_path(host)
+    argv = H.build_tmux_session_argv(
+        tmux_path=tmux_path, claude_path=claude, workdir=workdir,
+        socket_path=socket, session_name="optio",
+        extra_env=None, claude_flags=[],
+    )
+    import shlex
+    cmd = " ".join(shlex.quote(a) for a in argv)
+    r = await host.run_command(cmd)
+    assert r.exit_code == 0, r.stderr
+    return tmux_path, socket
+
+
+@pytest.mark.skipif(_NO_TMUX, reason="tmux not installed on the worker")
+@pytest.mark.asyncio
+async def test_rescue_end_to_end_kills_orphan_and_snapshots(
+    mongo_db, tmp_path, ctx_and_captures,
+):
+    """Launch a real (shim) detached session, abandon it so it becomes an
+    orphan, then run _rescue_orphan_if_present and assert: the tmux session is
+    gone, no claude shim remains, and a fresh 'rescued' snapshot was inserted.
+
+    Manual run:
+        .venv/bin/python -m pytest \\
+          packages/optio-claudecode/tests/test_rescue_orphan.py \\
+          -k end_to_end -v
+    """
+    import asyncio
+
+    from optio_claudecode.snapshots import load_latest_snapshot
+    from optio_host.host import LocalHost
+
+    ctx, _cap, _flag = ctx_and_captures
+    ctx.resume = True
+
+    # (a)+(b) Build the LocalHost and launch the detached (shim) session on the
+    #         deterministic per-task socket.
+    taskdir = str(tmp_path / "task")
+    os.makedirs(taskdir, exist_ok=True)
+    host = LocalHost(taskdir=taskdir)
+    os.makedirs(host.workdir, exist_ok=True)
+
+    tmux_path, socket = await _launch_orphan_session(host)
+    # Confirm the orphan is actually alive before we rescue it.
+    assert await H.tmux_session_alive(host, tmux_path, socket, "optio")
+    pid_file = f"{host.workdir}/claude.pid"
+    for _ in range(30):
+        if os.path.exists(pid_file):
+            break
+        await asyncio.sleep(0.1)
+    assert os.path.exists(pid_file)
+    child_pid = int(open(pid_file).read().strip())
+
+    # (c) Crash simulation: we never captured an in-process handle, and we do
+    #     not tear the session down. The tmux/claude tree is the orphan.
+
+    config = ClaudeCodeTaskConfig(
+        consumer_instructions="(rescue e2e)",
+        supports_resume=True,
+        session_blob_encrypt=lambda b: b,
+        session_blob_decrypt=lambda b: b,
+    )
+
+    # (d) Rescue.
+    await S._rescue_orphan_if_present(ctx, host, config)
+
+    # (e) Assertions.
+    # The tmux session is gone (orphan killed before capture).
+    assert (await H.tmux_session_alive(host, tmux_path, socket, "optio")) is False
+    # The sleep shim child is reaped (kill-session SIGHUPs the pane tree).
+    await asyncio.sleep(0.3)
+    with pytest.raises(ProcessLookupError):
+        os.kill(child_pid, 0)
+
+    # A fresh 'rescued' snapshot was inserted.
+    snap = await load_latest_snapshot(
+        mongo_db, prefix=ctx._prefix, process_id=ctx.process_id,
+    )
+    assert snap is not None
+    assert snap["endState"] == "rescued"
+
+    # Marker cleared on success.
+    marker = f"{host.workdir.rstrip('/')}/.optio-rescue-pending"
+    r = await host.run_command(
+        f"test -e {marker} && echo Y || true"
+    )
+    assert "Y" not in r.stdout

optio_claudecode-0.2.4/tests/test_teardown_session_tree.py

@@ -0,0 +1,86 @@
+import pytest
+
+import optio_claudecode.host_actions as H
+
+
+@pytest.fixture
+def calls(monkeypatch):
+    rec = []
+
+    async def _kill_ttyd(host, socket):
+        rec.append(("ttyd_socket", socket))
+
+    async def _kill_session(host, tmux_path, socket, session):
+        rec.append(("kill_session", session))
+
+    async def _kill_claude(host, claude_path, **kw):
+        rec.append(("kill_claude", claude_path))
+
+    async def _await_gone(host, claude_path, **kw):
+        rec.append(("await_gone", claude_path))
+        return True
+
+    monkeypatch.setattr(H, "_kill_ttyd_by_socket", _kill_ttyd)
+    monkeypatch.setattr(H, "_kill_tmux_session", _kill_session)
+    monkeypatch.setattr(H, "kill_claude_processes", _kill_claude)
+    monkeypatch.setattr(H, "await_claude_gone", _await_gone)
+    return rec
+
+
+class _FakeHandle:
+    pass
+
+
+class _Host:
+    def __init__(self):
+        self.terminated = []
+
+    async def terminate_subprocess(self, handle, *, aggressive):
+        self.terminated.append((handle, aggressive))
+
+
+@pytest.mark.asyncio
+async def test_orphan_branch_uses_kill_ttyd_by_socket(calls):
+    host = _Host()
+    await H.teardown_session_tree(
+        host, tmux_path="tmux", tmux_socket="/tmp/s.sock",
+        tmux_session="optio", claude_path="/w/home/.local/bin/claude",
+        ttyd_handle=None, aggressive=True,
+    )
+    # All four steps, in order; orphan ttyd path; no terminate_subprocess.
+    assert [c[0] for c in calls] == [
+        "ttyd_socket", "kill_session", "kill_claude", "await_gone",
+    ]
+    assert host.terminated == []
+
+
+@pytest.mark.asyncio
+async def test_handle_branch_uses_terminate_subprocess(calls):
+    host = _Host()
+    handle = _FakeHandle()
+    await H.teardown_session_tree(
+        host, tmux_path="tmux", tmux_socket="/tmp/s.sock",
+        tmux_session="optio", claude_path="/w/home/.local/bin/claude",
+        ttyd_handle=handle, aggressive=False,
+    )
+    assert host.terminated == [(handle, False)]
+    # ttyd-by-socket NOT used when a handle is present.
+    assert [c[0] for c in calls] == ["kill_session", "kill_claude", "await_gone"]
+
+
+@pytest.mark.asyncio
+async def test_steps_are_best_effort(calls, monkeypatch):
+    # A failure in one step does not abort the rest.
+    async def _boom(host, socket):
+        raise RuntimeError("ttyd kill blew up")
+
+    monkeypatch.setattr(H, "_kill_ttyd_by_socket", _boom)
+    host = _Host()
+    # Should not raise.
+    await H.teardown_session_tree(
+        host, tmux_path="tmux", tmux_socket="/tmp/s.sock",
+        tmux_session="optio", claude_path="/w/home/.local/bin/claude",
+        ttyd_handle=None, aggressive=True,
+    )
+    # The remaining three steps still ran.
+    assert [c[0] for c in calls] == ["kill_session", "kill_claude", "await_gone"]