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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: optio-claudecode
-Version: 0.2.2
+Version: 0.2.3
 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

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "optio-claudecode"
-version = "0.2.2"
+version = "0.2.3"
 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"

{optio_claudecode-0.2.2 → optio_claudecode-0.2.3}/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.2 → optio_claudecode-0.2.3}/src/optio_claudecode/session.py

@@ -110,6 +110,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.
 
@@ -358,41 +363,27 @@ 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.
-            try:
-                await host_actions.kill_claude_processes(host, claude_path)
-            except Exception:
-                _LOG.exception("kill_claude_processes failed")
-            try:
-                await host_actions.await_claude_gone(host, claude_path)
-            except Exception:
-                _LOG.exception("await_claude_gone failed; proceeding to capture")
+                _LOG.exception("teardown_session_tree failed")
+            _trace("finally: teardown_session_tree DONE")
 
         if cred_watch_task is not None:
             cred_watch_task.cancel()
@@ -566,6 +557,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,

{optio_claudecode-0.2.2 → optio_claudecode-0.2.3}/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.3
 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

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

@@ -22,6 +22,7 @@ tests/test_await_claude_gone.py
 tests/test_cred_watcher.py
 tests/test_home_isolation.py
 tests/test_host_actions.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 +30,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 +48,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.3/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.3/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.3/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"]