mcp-yieldshell 1.1.0__tar.gz → 1.1.2__tar.gz

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-yieldshell
-Version: 1.1.0
+Version: 1.1.2
 Summary: A drop-in shell MCP that auto-yields long-running commands into managed background executions.
 Requires-Python: >=3.11
 Requires-Dist: mcp<2,>=1.9.0
@@ -227,7 +227,7 @@ Read stdout and/or stderr from a running or completed execution.
 * **Returns**:
   * `execution_id`, `status`, `exit_code`, `signal`, and `stdin_error` when initial input delivery failed. `stdout` and `stderr` text are included based on the `streams` filter — `"both"` includes both, `"stdout"` includes only `stdout`, and `"stderr"` includes only `stderr`.
   * Cursor fields: `start_seq` (position of the first byte returned), `next_seq` (cursor to use in the next `since_seq` read), and `latest_seq` (how far output has advanced overall — when it exceeds `next_seq`, more is waiting).
-  * Withheld-output flags: `capped` means more output is available and reading again continues from `next_seq`; `evicted` means output fell out of the ring buffer before it was read and cannot be recovered. When either is set, a `hint` field names the concrete follow-up call.
+  * Withheld-output flags: `capped` means more output is available and reading again continues from `next_seq`; `evicted` means output became unrecoverable before it could be read. This normally means it fell out of the ring buffer; it can also mean retention concurrently removed the completed record. When either is set, a `hint` field names the concrete follow-up action.
 
 ### `write`
 Write text input to the standard input (`stdin`) of a running execution.
@@ -337,7 +337,7 @@ To avoid sending duplicate data over the MCP protocol (which can consume context
 6. Requests that pass `since_seq`, pass `tail_lines`, or narrow `streams` are treated as **out-of-band**: they neither consult nor advance the server-side cursor. This means a peek at the tail or at stderr cannot silently skip output the polling stream has not seen yet.
 7. Two distinct flags report output the response did not carry, and they call for different responses:
    * `capped` — the response cap stopped the read short. The remainder is still buffered; read again to continue, or pass the returned `next_seq` as `since_seq`. The `hint` field spells out the call.
-   * `evicted` — output exceeded the ring buffer's capacity before it was read and is permanently gone. Retrying cannot recover it; poll more often or raise `YIELDSHELL_MAX_BUFFER_BYTES`. Reads report eviction only when their requested range overlaps evicted data.
+   * `evicted` — output is permanently gone. This normally means it exceeded the ring buffer's capacity before it was read; a completed record reaped concurrently with a capped response is also reported as unrecoverable instead of offering a dangling follow-up read. Retrying cannot recover it; poll more often, raise `YIELDSHELL_MAX_BUFFER_BYTES`, or increase terminal retention as indicated by the response hint.
 8. `latest_seq` reports how far output has advanced overall. `latest_seq > next_seq` means more is already waiting; `latest_seq == next_seq` means the caller is fully caught up.
 9. Because retention (`YIELDSHELL_MAX_BUFFER_BYTES`, 256 KB per stream) is much larger than the per-response cap (`YIELDSHELL_MAX_OUTPUT_BYTES`, 20 KB), a cursor normally stays resolvable across polling gaps.
 
@@ -383,6 +383,7 @@ Configure the server by setting these environment variables prior to launch:
 * **Agent Process Termination**: `KILLS_AGENT_PROCESS` covers commands that may terminate the MCP client, agent, or related process running the agent workflow (e.g., `kill` commands targeting the agent PID, or commands that cause the agent to exit). This is distinct from `STOPS_OR_RESTARTS_SERVICES`, which covers OS-level services. Blocked by default; operators can override.
 * **Path Validation**: CWD path verification resolves traversal and symlinks, then requires the target to be an allowed root itself or a true descendant. Lexically similar siblings and symlink escapes are rejected before spawn.
 * **Additive Environments**: The `env` argument overlays existing env parameters. It merges with the parent process environment instead of completely replacing it, protecting critical OS vars.
+* **Linux Descendant Discovery**: Each Linux execution receives a random internal environment token. If a descendant creates a new session or process group, procfs discovery keeps ordinary daemonized descendants associated with the execution so `stop`, runtime timeout, and shutdown can signal them too. This is lifecycle containment, not a security sandbox: deliberately replacing the inherited environment can evade discovery.
 * **Opt-in Best-effort Redaction**: Redaction is disabled unless `YIELDSHELL_REDACT_ENV_REGEX` is configured. When enabled, matching environment values are snapshotted at startup, ordered longest first, and values shorter than 8 characters are excluded to avoid corrupting ordinary output. Matching values supplied through an `env` overlay are added for that process. Redaction is applied while streams are drained, including across subprocess chunks and incremental read pages. Restart the server to refresh the parent-environment snapshot after changes. Redaction does not remove variables from subprocess environments, and secrets not selected by the regex or printed through transformed formats might not be caught.
 
 ## Lifecycle and Compatibility
@@ -391,7 +392,10 @@ YieldShell gives graceful termination 10 seconds before force-killing, waits up
 to 5 seconds for a POSIX process group to disappear, and allows up to 3 seconds
 for final stream draining. On stdio server shutdown, all live managed
 executions are terminated concurrently using the same bounded graceful/forced
-policy. Already-terminal records are not changed by shutdown.
+policy. Already-terminal records are not changed by shutdown. If a process
+group survives force-kill or a pending spawn ignores cancellation, shutdown
+fails visibly, remains incomplete, and can be retried instead of silently
+orphaning live work.
 
 `execution_id` is an opaque, server-generated string. Clients must pass it
 through unchanged rather than parsing or pattern-matching it. Its current
@@ -421,7 +425,8 @@ unchanged to `read`, `write`, `wait`, and `stop`. Calls that send the OS
 
 ## Platform Support
 
-* **POSIX (Linux & macOS)**: Fully supported. Spawns processes in distinct sessions (`start_new_session=True`), allowing `stop`, runtime timeout, and server shutdown signals (`SIGTERM`/`SIGKILL`) to target the entire process group. This cleans up child processes started by managed commands.
+* **Linux**: Fully supported. Commands start in distinct sessions (`start_new_session=True`), and `stop`, runtime timeout, and shutdown target the process group. Procfs token discovery also tracks ordinary descendants that explicitly create another session or process group.
+* **macOS**: Supported with POSIX process-group controls. Descendants that explicitly leave the managed process group are outside that mechanism and may persist.
 * **Windows**: Supported with best-effort process controls. Windows lacks native POSIX process-group signals, so `stop`, `timeout_ms`, and server shutdown act on the primary process; child subprocesses might persist if they do not exit cleanly.
 
 ---

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/README.md

@@ -219,7 +219,7 @@ Read stdout and/or stderr from a running or completed execution.
 * **Returns**:
   * `execution_id`, `status`, `exit_code`, `signal`, and `stdin_error` when initial input delivery failed. `stdout` and `stderr` text are included based on the `streams` filter — `"both"` includes both, `"stdout"` includes only `stdout`, and `"stderr"` includes only `stderr`.
   * Cursor fields: `start_seq` (position of the first byte returned), `next_seq` (cursor to use in the next `since_seq` read), and `latest_seq` (how far output has advanced overall — when it exceeds `next_seq`, more is waiting).
-  * Withheld-output flags: `capped` means more output is available and reading again continues from `next_seq`; `evicted` means output fell out of the ring buffer before it was read and cannot be recovered. When either is set, a `hint` field names the concrete follow-up call.
+  * Withheld-output flags: `capped` means more output is available and reading again continues from `next_seq`; `evicted` means output became unrecoverable before it could be read. This normally means it fell out of the ring buffer; it can also mean retention concurrently removed the completed record. When either is set, a `hint` field names the concrete follow-up action.
 
 ### `write`
 Write text input to the standard input (`stdin`) of a running execution.
@@ -329,7 +329,7 @@ To avoid sending duplicate data over the MCP protocol (which can consume context
 6. Requests that pass `since_seq`, pass `tail_lines`, or narrow `streams` are treated as **out-of-band**: they neither consult nor advance the server-side cursor. This means a peek at the tail or at stderr cannot silently skip output the polling stream has not seen yet.
 7. Two distinct flags report output the response did not carry, and they call for different responses:
    * `capped` — the response cap stopped the read short. The remainder is still buffered; read again to continue, or pass the returned `next_seq` as `since_seq`. The `hint` field spells out the call.
-   * `evicted` — output exceeded the ring buffer's capacity before it was read and is permanently gone. Retrying cannot recover it; poll more often or raise `YIELDSHELL_MAX_BUFFER_BYTES`. Reads report eviction only when their requested range overlaps evicted data.
+   * `evicted` — output is permanently gone. This normally means it exceeded the ring buffer's capacity before it was read; a completed record reaped concurrently with a capped response is also reported as unrecoverable instead of offering a dangling follow-up read. Retrying cannot recover it; poll more often, raise `YIELDSHELL_MAX_BUFFER_BYTES`, or increase terminal retention as indicated by the response hint.
 8. `latest_seq` reports how far output has advanced overall. `latest_seq > next_seq` means more is already waiting; `latest_seq == next_seq` means the caller is fully caught up.
 9. Because retention (`YIELDSHELL_MAX_BUFFER_BYTES`, 256 KB per stream) is much larger than the per-response cap (`YIELDSHELL_MAX_OUTPUT_BYTES`, 20 KB), a cursor normally stays resolvable across polling gaps.
 
@@ -375,6 +375,7 @@ Configure the server by setting these environment variables prior to launch:
 * **Agent Process Termination**: `KILLS_AGENT_PROCESS` covers commands that may terminate the MCP client, agent, or related process running the agent workflow (e.g., `kill` commands targeting the agent PID, or commands that cause the agent to exit). This is distinct from `STOPS_OR_RESTARTS_SERVICES`, which covers OS-level services. Blocked by default; operators can override.
 * **Path Validation**: CWD path verification resolves traversal and symlinks, then requires the target to be an allowed root itself or a true descendant. Lexically similar siblings and symlink escapes are rejected before spawn.
 * **Additive Environments**: The `env` argument overlays existing env parameters. It merges with the parent process environment instead of completely replacing it, protecting critical OS vars.
+* **Linux Descendant Discovery**: Each Linux execution receives a random internal environment token. If a descendant creates a new session or process group, procfs discovery keeps ordinary daemonized descendants associated with the execution so `stop`, runtime timeout, and shutdown can signal them too. This is lifecycle containment, not a security sandbox: deliberately replacing the inherited environment can evade discovery.
 * **Opt-in Best-effort Redaction**: Redaction is disabled unless `YIELDSHELL_REDACT_ENV_REGEX` is configured. When enabled, matching environment values are snapshotted at startup, ordered longest first, and values shorter than 8 characters are excluded to avoid corrupting ordinary output. Matching values supplied through an `env` overlay are added for that process. Redaction is applied while streams are drained, including across subprocess chunks and incremental read pages. Restart the server to refresh the parent-environment snapshot after changes. Redaction does not remove variables from subprocess environments, and secrets not selected by the regex or printed through transformed formats might not be caught.
 
 ## Lifecycle and Compatibility
@@ -383,7 +384,10 @@ YieldShell gives graceful termination 10 seconds before force-killing, waits up
 to 5 seconds for a POSIX process group to disappear, and allows up to 3 seconds
 for final stream draining. On stdio server shutdown, all live managed
 executions are terminated concurrently using the same bounded graceful/forced
-policy. Already-terminal records are not changed by shutdown.
+policy. Already-terminal records are not changed by shutdown. If a process
+group survives force-kill or a pending spawn ignores cancellation, shutdown
+fails visibly, remains incomplete, and can be retried instead of silently
+orphaning live work.
 
 `execution_id` is an opaque, server-generated string. Clients must pass it
 through unchanged rather than parsing or pattern-matching it. Its current
@@ -413,7 +417,8 @@ unchanged to `read`, `write`, `wait`, and `stop`. Calls that send the OS
 
 ## Platform Support
 
-* **POSIX (Linux & macOS)**: Fully supported. Spawns processes in distinct sessions (`start_new_session=True`), allowing `stop`, runtime timeout, and server shutdown signals (`SIGTERM`/`SIGKILL`) to target the entire process group. This cleans up child processes started by managed commands.
+* **Linux**: Fully supported. Commands start in distinct sessions (`start_new_session=True`), and `stop`, runtime timeout, and shutdown target the process group. Procfs token discovery also tracks ordinary descendants that explicitly create another session or process group.
+* **macOS**: Supported with POSIX process-group controls. Descendants that explicitly leave the managed process group are outside that mechanism and may persist.
 * **Windows**: Supported with best-effort process controls. Windows lacks native POSIX process-group signals, so `stop`, `timeout_ms`, and server shutdown act on the primary process; child subprocesses might persist if they do not exit cleanly.
 
 ---

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-yieldshell"
-version = "1.1.0"
+version = "1.1.2"
 description = "A drop-in shell MCP that auto-yields long-running commands into managed background executions."
 readme = "README.md"
 requires-python = ">=3.11"

mcp_yieldshell-1.1.2/src/mcp_yieldshell/execution/containment.py

@@ -0,0 +1,71 @@
+"""Linux containment helpers for descendants that leave their process group."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import signal
+import sys
+
+EXECUTION_TOKEN_ENV = "_MCP_YIELDSHELL_EXECUTION_TOKEN"
+
+
+def new_execution_token() -> str | None:
+    """Return a process-discovery token on platforms that expose procfs."""
+    if not sys.platform.startswith("linux") or not os.path.isdir("/proc"):
+        return None
+    return secrets.token_hex(16)
+
+
+def contained_process_ids(token: str | None) -> set[int]:
+    """Find live processes whose initial environment carries ``token``."""
+    if token is None:
+        return set()
+    expected = f"{EXECUTION_TOKEN_ENV}={token}".encode()
+    found: set[int] = set()
+    try:
+        entries = os.scandir("/proc")
+    except OSError:
+        return found
+    with entries:
+        for entry in entries:
+            if not entry.name.isdecimal():
+                continue
+            pid = int(entry.name)
+            if pid == os.getpid():
+                continue
+            try:
+                with open(f"/proc/{pid}/environ", "rb") as environ_file:
+                    environment = environ_file.read()
+            except (OSError, ValueError):
+                continue
+            if expected in environment.split(b"\0"):
+                found.add(pid)
+    return found
+
+
+def contained_processes_exist(token: str | None) -> bool:
+    """Return whether any process carrying ``token`` is still observable."""
+    return bool(contained_process_ids(token))
+
+
+def signal_contained_processes(
+    token: str | None,
+    sig: signal.Signals,
+    *,
+    exclude_process_group_id: int | None = None,
+) -> None:
+    """Signal tagged processes outside the original managed process group."""
+    for pid in contained_process_ids(token):
+        if exclude_process_group_id is not None:
+            try:
+                if os.getpgid(pid) == exclude_process_group_id:
+                    continue
+            except ProcessLookupError:
+                continue
+            except PermissionError:
+                pass
+        try:
+            os.kill(pid, sig)
+        except (ProcessLookupError, PermissionError):
+            pass

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/src/mcp_yieldshell/execution/managed.py

@@ -30,6 +30,8 @@ class ManagedExecution:
         "_seq_source",
         "_timeout_triggered",
         "sensitive_env",
+        "containment_token",
+        "contained_processes_exited",
     )
 
     def __init__(
@@ -39,6 +41,7 @@ class ManagedExecution:
         max_buffer_bytes: int,
         process_group_id: int | None = None,
         sensitive_env: SensitiveEnv = (),
+        containment_token: str | None = None,
     ) -> None:
         self.info = info
         self.proc = proc
@@ -61,6 +64,8 @@ class ManagedExecution:
         self.stdin_error: str | None = None
         self._timeout_triggered = False
         self.sensitive_env = sensitive_env
+        self.containment_token = containment_token
+        self.contained_processes_exited = False
 
     @property
     def latest_seq(self) -> int:

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/src/mcp_yieldshell/execution/manager.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import codecs
 import os
+import signal
 import sys
 import time
 import uuid
@@ -25,6 +26,12 @@ from ..security import (
 )
 from ..side_effects import validate_side_effects
 from ..types import ExecutionInfo, ExecutionStatus, SideEffect
+from .containment import (
+    EXECUTION_TOKEN_ENV,
+    contained_processes_exist,
+    new_execution_token,
+    signal_contained_processes,
+)
 from .managed import ManagedExecution
 from .ring_buffer import RingBuffer, read_buffers, tail_start_seq
 from .spawn import kill_process, spawn_process, terminate_process
@@ -64,7 +71,12 @@ class ExecutionManager:
         for task in tasks:
             task.cancel()
         if tasks:
-            await asyncio.gather(*tasks, return_exceptions=True)
+            done, _ = await asyncio.wait(
+                tasks,
+                timeout=PENDING_SPAWN_SHUTDOWN_MS / 1000.0,
+            )
+            if done:
+                await asyncio.gather(*done, return_exceptions=True)
 
     def _release_spawn_reservation(
         self, spawn_owner: asyncio.Task[Any] | None
@@ -80,6 +92,7 @@ class ExecutionManager:
         proc: asyncio.subprocess.Process,
         process_group_id: int | None,
         drain_tasks: list[asyncio.Task[None]],
+        containment_token: str | None = None,
     ) -> None:
         for task in drain_tasks:
             if not task.done():
@@ -87,6 +100,11 @@ class ExecutionManager:
         if drain_tasks:
             await asyncio.gather(*drain_tasks, return_exceptions=True)
         await kill_process(proc, process_group_id)
+        signal_contained_processes(
+            containment_token,
+            signal.SIGKILL,
+            exclude_process_group_id=process_group_id,
+        )
         try:
             await asyncio.wait_for(proc.wait(), timeout=1.0)
         except (asyncio.TimeoutError, ProcessLookupError):
@@ -187,6 +205,18 @@ class ExecutionManager:
             fields["hint"] = " ".join(hints)
         return fields
 
+    @staticmethod
+    def _mark_snapshot_unrecoverable(snapshot: dict[str, Any]) -> None:
+        """Replace a paging promise after its execution record was reaped."""
+        if not snapshot["capped"]:
+            return
+        snapshot["capped"] = False
+        snapshot["evicted"] = True
+        snapshot["hint"] = (
+            "Additional execution output was omitted and cannot be recovered "
+            "because retention removed the completed record."
+        )
+
     def _redact(self, mp: ManagedExecution, text: str) -> str:
         return redact_text(self._config, text, mp.sensitive_env)
 
@@ -354,6 +384,9 @@ class ExecutionManager:
 
         try:
             env = build_env(self._config, env_overlay)
+            containment_token = new_execution_token()
+            if containment_token is not None:
+                env[EXECUTION_TOKEN_ENV] = containment_token
             effective_yield = self._clamp_yield_ms(yield_ms)
             effective_timeout = self._clamp_timeout_ms(timeout_ms)
             effective_max_output = self._max_output(max_output_bytes)
@@ -389,6 +422,7 @@ class ExecutionManager:
             self._config.max_buffer_bytes,
             process_group_id,
             collect_sensitive_env(self._config, env_overlay),
+            containment_token,
         )
 
         # Start drain tasks immediately after spawn to prevent blocking on full pipe buffers
@@ -417,12 +451,22 @@ class ExecutionManager:
         except asyncio.CancelledError:
             self._release_spawn_reservation(spawn_owner)
             await asyncio.shield(
-                self._reject_spawned_execution(proc, process_group_id, drain_tasks)
+                self._reject_spawned_execution(
+                    proc,
+                    process_group_id,
+                    drain_tasks,
+                    containment_token,
+                )
             )
             raise
 
         if reject_for_shutdown:
-            await self._reject_spawned_execution(proc, process_group_id, drain_tasks)
+            await self._reject_spawned_execution(
+                proc,
+                process_group_id,
+                drain_tasks,
+                containment_token,
+            )
             return self._shutdown_reject_response()
 
         mp.completion_task = asyncio.create_task(
@@ -462,6 +506,11 @@ class ExecutionManager:
 
         # Prepare output for response
         snapshot = self._read_snapshot(mp, effective_max_output)
+        addressable = self._executions.get(execution_id) is mp
+        if not addressable:
+            # Retention removed the terminal record before this response was
+            # assembled. Do not emit a dangling read hint.
+            self._mark_snapshot_unrecoverable(snapshot)
         # Every branch carries the cursor so a caller can keep reading without
         # replaying output it already received.
         common = {"duration_ms": round(duration_ms, 1), **snapshot}
@@ -472,7 +521,6 @@ class ExecutionManager:
         # Response matrix: failed_to_start returns before a record is created;
         # every retained result is addressable by its opaque execution ID and
         # exposes the initial shell's OS process ID when one is available.
-        addressable = self._executions.get(execution_id) is mp
         identifiers: dict[str, Any] = {}
         if addressable:
             identifiers["execution_id"] = execution_id
@@ -562,21 +610,50 @@ class ExecutionManager:
 
     def _process_group_exists(self, mp: ManagedExecution) -> bool:
         if mp.process_group_exited:
-            return False
+            return self._contained_processes_exist(mp)
         if sys.platform == "win32":
             exists = mp.proc.returncode is None
             if not exists:
                 mp.process_group_exited = True
-            return exists
+            return exists or self._contained_processes_exist(mp)
         try:
             os.killpg(self._process_group_id(mp), 0)
         except ProcessLookupError:
             mp.process_group_exited = True
-            return False
+            return self._contained_processes_exist(mp)
         except PermissionError:
             return True
         return True
 
+    @staticmethod
+    def _contained_processes_exist(mp: ManagedExecution) -> bool:
+        if mp.contained_processes_exited:
+            return False
+        exists = contained_processes_exist(mp.containment_token)
+        if not exists:
+            # Once the original group is gone and no tagged descendants exist,
+            # no process remains that could create another tagged descendant.
+            mp.contained_processes_exited = True
+        return exists
+
+    @staticmethod
+    def _signal_contained_processes(
+        mp: ManagedExecution, sig: signal.Signals
+    ) -> None:
+        signal_contained_processes(
+            mp.containment_token,
+            sig,
+            exclude_process_group_id=mp.process_group_id,
+        )
+
+    async def _terminate_execution(self, mp: ManagedExecution) -> None:
+        await terminate_process(mp.proc, mp.process_group_id)
+        self._signal_contained_processes(mp, signal.SIGTERM)
+
+    async def _kill_execution(self, mp: ManagedExecution) -> None:
+        await kill_process(mp.proc, mp.process_group_id)
+        self._signal_contained_processes(mp, signal.SIGKILL)
+
     async def _drain_stream(
         self,
         stream: asyncio.StreamReader | None,
@@ -805,23 +882,24 @@ class ExecutionManager:
             await asyncio.sleep(timeout_sec)
         except asyncio.CancelledError:
             return
-        # The subprocess may have exited naturally while its completion tracker
-        # was waiting to run. Do not relabel that race as a timeout.
-        if mp.proc.returncode is not None and not self._process_group_exists(mp):
+        # Managed processes may have exited naturally while the completion
+        # tracker is still waiting to publish the subprocess return code.
+        # Containment disappearance is authoritative; do not relabel that race.
+        if not self._process_group_exists(mp):
             return
         if not self._has_live_work(mp):
             return
         mp._timeout_triggered = True
         mp.info.status = ExecutionStatus.TIMED_OUT
         # Graceful termination
-        await terminate_process(mp.proc, mp.process_group_id)
+        await self._terminate_execution(mp)
         grace_period = GRACEFUL_STOP_MS / 1000.0
         await self._wait_for_process_group_exit(mp, timeout_sec=grace_period)
 
         if self._process_group_exists(mp):
             # Force kill any children that survived graceful termination, even if
             # the shell process already exited.
-            await kill_process(mp.proc, mp.process_group_id)
+            await self._kill_execution(mp)
             await self._wait_for_process_group_exit(
                 mp, timeout_sec=PROCESS_GROUP_EXIT_MS / 1000.0
             )
@@ -984,6 +1062,8 @@ class ExecutionManager:
 
         effective_max = self._max_output(max_output_bytes)
         snapshot = self._read_snapshot(mp, effective_max, since_seq, tail_lines)
+        if self._executions.get(execution_id) is not mp:
+            self._mark_snapshot_unrecoverable(snapshot)
 
         return self._with_stdin_error(mp, {
             "execution_id": execution_id,
@@ -1051,6 +1131,8 @@ class ExecutionManager:
                     pass
         else:
             await terminate_process(mp.proc)
+        if sys.platform != "win32":
+            self._signal_contained_processes(mp, sig)
 
         # Wait for grace period
         # Reserve time for force-kill observation, final drain, and subprocess
@@ -1062,7 +1144,7 @@ class ExecutionManager:
 
         if self._process_group_exists(mp):
             # The primary shell may exit before a resistant descendant.
-            await kill_process(mp.proc, mp.process_group_id)
+            await self._kill_execution(mp)
             await self._wait_for_process_group_exit(
                 mp, timeout_sec=PROCESS_GROUP_EXIT_MS / 1000.0
             )
@@ -1195,12 +1277,28 @@ class ExecutionManager:
                     name="yieldshell-shutdown",
                 )
                 self._shutdown_task = task
-        await asyncio.shield(task)
+        try:
+            await asyncio.shield(task)
+        except BaseException:
+            # A failed teardown must be retryable. Keep an in-progress task
+            # shared when only this caller was cancelled, but release a settled
+            # failed task so a later shutdown call can try containment again.
+            async with self._shutdown_lock:
+                if self._shutdown_task is task and task.done():
+                    self._shutdown_task = None
+            raise
 
     async def _run_shutdown(self) -> None:
         """Perform the shutdown sequence once, independently of caller cancellation."""
         await self._wait_for_no_pending_spawns()
         await self._cancel_pending_spawns()
+        async with self._shutdown_lock:
+            pending_spawns = self._pending_spawns
+        if pending_spawns:
+            raise RuntimeError(
+                "Server shutdown could not settle "
+                f"{pending_spawns} pending spawn call(s)"
+            )
 
         while True:
             live = [
@@ -1217,7 +1315,7 @@ class ExecutionManager:
             running_at_start = {id(mp) for mp in live if not self._is_terminal(mp)}
 
             await asyncio.gather(
-                *(terminate_process(mp.proc, mp.process_group_id) for mp in live),
+                *(self._terminate_execution(mp) for mp in live),
                 return_exceptions=True,
             )
 
@@ -1229,7 +1327,7 @@ class ExecutionManager:
 
             survivors = [mp for mp in live if self._process_group_exists(mp)]
             await asyncio.gather(
-                *(kill_process(mp.proc, mp.process_group_id) for mp in survivors),
+                *(self._kill_execution(mp) for mp in survivors),
                 return_exceptions=True,
             )
             await asyncio.gather(
@@ -1252,8 +1350,10 @@ class ExecutionManager:
                 *(self._settle_completion(mp) for mp in live),
                 return_exceptions=True,
             )
+            survivors = [mp for mp in live if self._process_group_exists(mp)]
+            survivor_ids = {id(mp) for mp in survivors}
             for mp in live:
-                if not self._process_group_exists(mp):
+                if id(mp) not in survivor_ids:
                     self._mark_ended(mp)
 
             for mp in live:
@@ -1266,9 +1366,13 @@ class ExecutionManager:
                 if mp.stdin_task is not None and not mp.stdin_task.done():
                     mp.stdin_task.cancel()
                 self._close_output_pipes(mp)
-                if id(mp) in running_at_start and mp.info.status in (
-                    ExecutionStatus.RUNNING,
-                    ExecutionStatus.COMPLETED,
+                if (
+                    id(mp) not in survivor_ids
+                    and id(mp) in running_at_start
+                    and mp.info.status in (
+                        ExecutionStatus.RUNNING,
+                        ExecutionStatus.COMPLETED,
+                    )
                 ):
                     mp.info.status = ExecutionStatus.STOPPED
                 mp.completion_event.set()
@@ -1287,6 +1391,12 @@ class ExecutionManager:
             if tasks:
                 await asyncio.gather(*tasks, return_exceptions=True)
 
+            if survivors:
+                raise RuntimeError(
+                    "Server shutdown could not terminate process group(s): "
+                    + ", ".join(mp.info.execution_id for mp in survivors)
+                )
+
             async with self._shutdown_lock:
                 self._shutdown_complete = True
             return

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/src/mcp_yieldshell/execution/ring_buffer.py

@@ -117,9 +117,15 @@ class RingBuffer:
 
     def clear(self) -> None:
         """Clear all buffered data."""
+        if self._chunks:
+            last_start, last_chunk = self._chunks[-1]
+            cleared_until = last_start + len(last_chunk)
+            self._evicted_until_seq = max(
+                self._evicted_until_seq or cleared_until,
+                cleared_until,
+            )
         self._chunks.clear()
         self._retained_bytes = 0
-        self._evicted_until_seq = None
 
 
 def read_buffers(

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/tests/test_lifecycle_hardening.py

@@ -2,6 +2,7 @@
 
 import asyncio
 import os
+import shutil
 import signal
 import sys
 import time
@@ -161,6 +162,56 @@ class TestConcurrentShutdown:
         assert manager._shutdown_complete is True
         assert managed.info.status == ExecutionStatus.STOPPED
 
+    @pytest.mark.asyncio
+    async def test_force_kill_survivor_keeps_shutdown_retryable(self, monkeypatch):
+        manager = ExecutionManager(Config())
+        process = MagicMock()
+        process.pid = 12345
+        process.returncode = None
+        process.stdin = None
+        process.stdout = None
+        process.stderr = None
+        info = ExecutionInfo(
+            execution_id="shutdown-survivor",
+            process_id=process.pid,
+            command="resistant",
+            cwd=os.getcwd(),
+            name=None,
+            status=ExecutionStatus.RUNNING,
+            started_at=time.time(),
+            start_monotonic=time.monotonic(),
+        )
+        managed = ManagedExecution(info, process, 100, process_group_id=process.pid)
+        manager._executions[info.execution_id] = managed
+        group_alive = True
+
+        monkeypatch.setattr(
+            manager, "_process_group_exists", lambda _mp: group_alive
+        )
+        monkeypatch.setattr(
+            "mcp_yieldshell.execution.manager.terminate_process", AsyncMock()
+        )
+        monkeypatch.setattr(
+            "mcp_yieldshell.execution.manager.kill_process", AsyncMock()
+        )
+        monkeypatch.setattr("mcp_yieldshell.execution.manager.GRACEFUL_STOP_MS", 0)
+        monkeypatch.setattr(
+            "mcp_yieldshell.execution.manager.PROCESS_GROUP_EXIT_MS", 0
+        )
+        monkeypatch.setattr("mcp_yieldshell.execution.manager.FINAL_DRAIN_MS", 0)
+
+        with pytest.raises(RuntimeError, match="shutdown.*process group"):
+            await manager.shutdown()
+
+        assert manager._shutdown_complete is False
+        assert managed.info.status == ExecutionStatus.RUNNING
+
+        group_alive = False
+        await manager.shutdown()
+
+        assert manager._shutdown_complete is True
+        assert managed.info.status == ExecutionStatus.STOPPED
+
 
 class TestAutomaticRetention:
     @pytest.mark.asyncio
@@ -188,8 +239,10 @@ class TestAutomaticRetention:
         )
 
         assert result["status"] == "completed"
-        assert result["capped"] is True
+        assert result["capped"] is False
+        assert result["evicted"] is True
         assert "execution_id" not in result
+        assert "cannot be recovered" in result["hint"]
 
     @pytest.mark.asyncio
     async def test_reaps_every_terminal_state_and_ids_become_unknown(self, monkeypatch):
@@ -264,6 +317,37 @@ class TestAutomaticRetention:
         result = await manager.cleanup(completed_older_than_ms=0)
         assert result["removed"] == 1
 
+    @pytest.mark.asyncio
+    async def test_wait_does_not_offer_paging_after_concurrent_cleanup(
+        self, monkeypatch
+    ):
+        manager = ExecutionManager(Config())
+        started = await manager.execute_command("printf abcdef", side_effects=NONE)
+        execution_id = started["execution_id"]
+        managed = manager.get_execution(execution_id)
+        assert managed is not None
+        managed.info.ended_at = time.time() - 1
+
+        async def cleanup_during_wait(_managed, _timeout_sec):
+            cleanup = await manager.cleanup(completed_older_than_ms=0)
+            assert cleanup["removed"] == 1
+            return True
+
+        monkeypatch.setattr(manager, "_await_live_work_end", cleanup_during_wait)
+
+        result = await manager.wait_execution(
+            execution_id,
+            timeout_ms=100,
+            max_output_bytes=2,
+            since_seq=1,
+        )
+
+        assert manager.get_execution(execution_id) is None
+        assert result["stdout"] == "ab"
+        assert result["capped"] is False
+        assert result["evicted"] is True
+        assert "cannot be recovered" in result["hint"]
+
     @pytest.mark.asyncio
     @pytest.mark.skipif(sys.platform == "win32", reason="POSIX process groups only")
     async def test_live_descendant_counts_toward_limit_and_survives_cleanup(
@@ -326,6 +410,25 @@ class TestAutomaticRetention:
         monkeypatch.setattr(os, "killpg", lambda *_: None)
         assert manager._process_group_exists(mp) is False
 
+    @pytest.mark.asyncio
+    async def test_absent_linux_descendants_are_not_rescanned(self, monkeypatch):
+        manager = ExecutionManager(Config())
+        await manager.execute_command("echo done", side_effects=NONE)
+        execution_id = manager.list_executions(limit=1)["executions"][0]["execution_id"]
+        managed = manager.get_execution(execution_id)
+        assert managed is not None
+        managed.process_group_exited = True
+        managed.containment_token = "test-token"
+        managed.contained_processes_exited = False
+        scan = MagicMock(return_value=False)
+        monkeypatch.setattr(
+            "mcp_yieldshell.execution.manager.contained_processes_exist", scan
+        )
+
+        assert manager._process_group_exists(managed) is False
+        assert manager._process_group_exists(managed) is False
+        scan.assert_called_once_with("test-token")
+
     @pytest.mark.asyncio
     async def test_concurrent_spawn_reservation_enforces_process_limit(self, monkeypatch):
         monkeypatch.setenv("YIELDSHELL_MAX_PROCESSES", "1")
@@ -343,6 +446,42 @@ class TestAutomaticRetention:
         await manager.stop_execution(running["execution_id"], force_after_ms=100)
 
 
+class TestTimeoutRaces:
+    @pytest.mark.asyncio
+    async def test_timeout_does_not_relabel_an_already_exited_process_group(
+        self, monkeypatch
+    ):
+        manager = ExecutionManager(Config())
+        process = MagicMock()
+        process.pid = 12345
+        process.returncode = None
+        process.stdin = None
+        process.stdout = None
+        process.stderr = None
+        info = ExecutionInfo(
+            execution_id="timeout-race",
+            process_id=process.pid,
+            command="already exited",
+            cwd=os.getcwd(),
+            name=None,
+            status=ExecutionStatus.RUNNING,
+            started_at=time.time(),
+            start_monotonic=time.monotonic(),
+        )
+        managed = ManagedExecution(info, process, 100, process_group_id=process.pid)
+        terminate = AsyncMock()
+        monkeypatch.setattr(manager, "_process_group_exists", lambda _mp: False)
+        monkeypatch.setattr(
+            "mcp_yieldshell.execution.manager.terminate_process", terminate
+        )
+
+        await manager._handle_timeout(managed, timeout_sec=0)
+
+        assert managed.info.status == ExecutionStatus.RUNNING
+        assert managed._timeout_triggered is False
+        terminate.assert_not_awaited()
+
+
 @pytest.mark.skipif(sys.platform == "win32", reason="POSIX process groups only")
 class TestManagerShutdown:
     @pytest.fixture(autouse=True)
@@ -395,6 +534,153 @@ class TestManagerShutdown:
             with pytest.raises(ProcessLookupError):
                 os.killpg(group, 0)
 
+    @pytest.mark.asyncio
+    @pytest.mark.skipif(
+        not sys.platform.startswith("linux") or shutil.which("setsid") is None,
+        reason="Linux procfs and setsid are required",
+    )
+    async def test_shutdown_kills_descendant_that_leaves_process_group(self):
+        manager = ExecutionManager(Config())
+        child_pid: int | None = None
+        try:
+            result = await manager.execute_command(
+                "setsid sh -c 'trap \"\" HUP TERM; echo CHILD=$$; exec sleep 30'",
+                yield_ms=0,
+                timeout_ms=0,
+                side_effects=NONE,
+            )
+            for _ in range(50):
+                page = await manager.read_execution_output(
+                    result["execution_id"], since_seq=1
+                )
+                if page["stdout"].startswith("CHILD="):
+                    child_pid = int(page["stdout"].split("=", 1)[1])
+                    break
+                await asyncio.sleep(0.02)
+            assert child_pid is not None
+            managed = manager.get_execution(result["execution_id"])
+            assert managed is not None and managed.process_group_id is not None
+            assert os.getpgid(child_pid) != managed.process_group_id
+
+            await manager.shutdown()
+
+            stat_path = f"/proc/{child_pid}/stat"
+            if os.path.exists(stat_path):
+                with open(stat_path) as stat_file:
+                    assert stat_file.read().split()[2] == "Z"
+        finally:
+            if child_pid is not None:
+                try:
+                    os.kill(child_pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+            if not manager._shutdown_complete:
+                await manager.shutdown()
+
+    @pytest.mark.asyncio
+    @pytest.mark.skipif(
+        not sys.platform.startswith("linux") or shutil.which("setsid") is None,
+        reason="Linux procfs and setsid are required",
+    )
+    async def test_daemonized_descendant_remains_managed_after_shell_exits(self):
+        manager = ExecutionManager(Config())
+        child_pid: int | None = None
+        try:
+            result = await manager.execute_command(
+                "setsid sh -c 'trap \"\" HUP TERM; exec sleep 30' "
+                ">/dev/null 2>&1 & echo CHILD=$!",
+                yield_ms=0,
+                timeout_ms=0,
+                side_effects=NONE,
+            )
+            execution_id = result["execution_id"]
+            for _ in range(100):
+                page = await manager.read_execution_output(
+                    execution_id, since_seq=1
+                )
+                if page["stdout"].startswith("CHILD="):
+                    child_pid = int(page["stdout"].split("=", 1)[1])
+                managed = manager.get_execution(execution_id)
+                if (
+                    child_pid is not None
+                    and managed is not None
+                    and managed.info.status == ExecutionStatus.COMPLETED
+                ):
+                    break
+                await asyncio.sleep(0.02)
+
+            assert child_pid is not None
+            managed = manager.get_execution(execution_id)
+            assert managed is not None
+            assert managed.info.status == ExecutionStatus.COMPLETED
+            assert manager.list_executions()["executions"][0]["status"] == "running"
+
+            await manager.shutdown()
+
+            stat_path = f"/proc/{child_pid}/stat"
+            if os.path.exists(stat_path):
+                with open(stat_path) as stat_file:
+                    assert stat_file.read().split()[2] == "Z"
+        finally:
+            if child_pid is not None:
+                try:
+                    os.kill(child_pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+            if not manager._shutdown_complete:
+                await manager.shutdown()
+
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize("termination", ("stop", "timeout"))
+    @pytest.mark.skipif(
+        not sys.platform.startswith("linux") or shutil.which("setsid") is None,
+        reason="Linux procfs and setsid are required",
+    )
+    async def test_stop_and_timeout_kill_descendant_outside_group(
+        self, termination
+    ):
+        manager = ExecutionManager(Config())
+        child_pid: int | None = None
+        try:
+            result = await manager.execute_command(
+                "setsid sh -c 'trap \"\" HUP TERM; echo CHILD=$$; exec sleep 30'",
+                yield_ms=0,
+                timeout_ms=100 if termination == "timeout" else 0,
+                side_effects=NONE,
+            )
+            execution_id = result["execution_id"]
+            for _ in range(50):
+                page = await manager.read_execution_output(
+                    execution_id, since_seq=1
+                )
+                if page["stdout"].startswith("CHILD="):
+                    child_pid = int(page["stdout"].split("=", 1)[1])
+                    break
+                await asyncio.sleep(0.02)
+            assert child_pid is not None
+
+            if termination == "stop":
+                stopped = await manager.stop_execution(
+                    execution_id, force_after_ms=100
+                )
+                assert stopped["stopped"] is True
+            else:
+                waited = await manager.wait_execution(execution_id, timeout_ms=3_000)
+                assert waited["status"] == "timed_out"
+                assert waited["wait_result"] == "exited"
+
+            stat_path = f"/proc/{child_pid}/stat"
+            if os.path.exists(stat_path):
+                with open(stat_path) as stat_file:
+                    assert stat_file.read().split()[2] == "Z"
+        finally:
+            if child_pid is not None:
+                try:
+                    os.kill(child_pid, signal.SIGKILL)
+                except ProcessLookupError:
+                    pass
+            await manager.shutdown()
+
     @pytest.mark.asyncio
     async def test_shutdown_force_kills_group_ignoring_termination(self):
         manager = ExecutionManager(Config())
@@ -935,6 +1221,44 @@ class TestShutdownSpawnRace:
         assert manager._pending_spawn_tasks == set()
         assert manager._shutdown_complete is True
 
+    @pytest.mark.asyncio
+    async def test_shutdown_reports_spawn_that_ignores_cancellation(
+        self, monkeypatch
+    ):
+        monkeypatch.setattr(
+            "mcp_yieldshell.execution.manager.PENDING_SPAWN_SHUTDOWN_MS", 20
+        )
+        spawn_started = asyncio.Event()
+        release_spawn = asyncio.Event()
+
+        async def stubborn_spawn(*_args, **_kwargs):
+            spawn_started.set()
+            try:
+                await release_spawn.wait()
+            except asyncio.CancelledError:
+                await release_spawn.wait()
+            return TestInitialStdinLifecycle.FakeProcess(None)
+
+        monkeypatch.setattr(
+            "mcp_yieldshell.execution.manager.spawn_process", stubborn_spawn
+        )
+        manager = ExecutionManager(Config())
+        execute_task = asyncio.create_task(
+            manager.execute_command("sleep 30", yield_ms=0, side_effects=NONE)
+        )
+        await spawn_started.wait()
+
+        try:
+            with pytest.raises(RuntimeError, match="pending spawn"):
+                await asyncio.wait_for(manager.shutdown(), timeout=0.5)
+            assert manager._shutdown_complete is False
+        finally:
+            release_spawn.set()
+            await execute_task
+            await manager.shutdown()
+
+        assert manager._shutdown_complete is True
+
 
 class TestWaitDeadline:
     @pytest.mark.asyncio

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/tests/test_release.py

@@ -227,6 +227,75 @@ class TestReleaseLockfileRefresh:
         assert remote_branch == local_head
         assert remote_tag == local_head
 
+    def test_release_resumes_after_commit_if_tagging_failed(
+        self, release_module, fake_repo, tmp_path, monkeypatch
+    ):
+        repo = fake_repo["repo"]
+        remote = tmp_path / "remote.git"
+        subprocess.run(
+            ["git", "init", "--bare", "-q", str(remote)],
+            check=True,
+            capture_output=True,
+        )
+        subprocess.run(
+            ["git", "remote", "add", "origin", str(remote)],
+            cwd=repo,
+            check=True,
+            capture_output=True,
+        )
+        monkeypatch.chdir(repo)
+        original_run_cmd = release_module.run_cmd
+
+        def fail_first_tag(cmd, check=True):
+            if cmd == "git tag v0.4.0":
+                raise SystemExit(1)
+            return original_run_cmd(cmd, check=check)
+
+        release_module.run_cmd = fail_first_tag
+        monkeypatch.setattr(sys, "argv", ["release.py", "0.4.0", "-y"])
+        with pytest.raises(SystemExit):
+            release_module.main()
+
+        assert release_module.get_current_version() == "0.4.0"
+        assert (
+            subprocess.run(
+                ["git", "log", "-1", "--format=%s"],
+                cwd=repo,
+                check=True,
+                capture_output=True,
+                text=True,
+            ).stdout.strip()
+            == "chore: bump version to v0.4.0"
+        )
+        assert (
+            subprocess.run(
+                ["git", "tag", "--list", "v0.4.0"],
+                cwd=repo,
+                check=True,
+                capture_output=True,
+                text=True,
+            ).stdout
+            == ""
+        )
+
+        release_module.run_cmd = original_run_cmd
+        release_module.main()
+
+        local_head = subprocess.run(
+            ["git", "rev-parse", "HEAD"],
+            cwd=repo,
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        remote_tag = subprocess.run(
+            ["git", "--git-dir", str(remote), "rev-parse", "refs/tags/v0.4.0^{commit}"],
+            check=True,
+            capture_output=True,
+            text=True,
+        ).stdout.strip()
+        assert remote_tag == local_head
+
     def test_uv_lock_failure_aborts_release(self, release_module, fake_repo, monkeypatch):
         """If ``uv lock`` fails, the release script exits non-zero before any commit/tag."""
         # Make the uv shim fail.

{mcp_yieldshell-1.1.0 → mcp_yieldshell-1.1.2}/tests/test_ring_buffer.py

@@ -262,6 +262,9 @@ class TestRingBufferUTF8:
         assert buf.byte_count == total
         result = buf.read()
         assert result["text"] == ""
+        assert result["start_seq"] == 6
+        assert result["next_seq"] == 6
+        assert result["evicted"] is True
 
 
 class TestTailStartSeq: