shell-session-manager 2.2.0__tar.gz → 2.2.1__tar.gz

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shell-session-manager
-Version: 2.2.0
+Version: 2.2.1
 Summary: Async subprocess session manager with incremental stdin/stdout/stderr support
 Author-Email: =?utf-8?b?WWFubGkg55uQ57KS?= <yanli@mail.one>
 License-Expression: Apache-2.0

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "shell-session-manager"
-version = "2.2.0"
+version = "2.2.1"
 description = "Async subprocess session manager with incremental stdin/stdout/stderr support"
 authors = [
     { name = "Yanli 盐粒", email = "yanli@mail.one" },

shell_session_manager-2.2.1/src/shell_session_manager/shellctl/sanitize_pty.py

@@ -0,0 +1,39 @@
+"""Minimal PTY sanitizer entrypoint used by tmux `pipe-pane`.
+
+This module intentionally stays isolated from the FastAPI/SQLite server stack
+so the tmux-side subprocess can touch its ready-file quickly and emit useful
+stderr when startup fails before any PTY output is drained.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+
+from shell_session_manager.shellctl.shared.sanitize import sanitize_pty_stream
+
+
+def parse_args():
+    """Parse the tiny CLI contract used by tmux `pipe-pane`."""
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--ready-file", type=Path)
+    return parser.parse_args()
+
+
+def run_sanitize_pty(ready_file: Path | None) -> None:
+    """Touch the ready file, then sanitize stdin into stdout."""
+
+    if ready_file is not None:
+        ready_file.touch()
+    sanitize_pty_stream(sys.stdin.buffer, sys.stdout.buffer)
+
+
+def main() -> None:
+    """Run the standalone PTY sanitizer module."""
+
+    args = parse_args()
+    run_sanitize_pty(args.ready_file)
+
+
+if __name__ == "__main__":
+    main()

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/__init__.py

@@ -11,7 +11,6 @@ from shell_session_manager.shellctl.server.cli import (
     cli,
     main,
     runner_exit_command,
-    sanitize_pty_command,
     serve_command,
 )
 from shell_session_manager.shellctl.server.config import ShellctlConfig
@@ -28,6 +27,5 @@ __all__ = [
     "create_app",
     "main",
     "runner_exit_command",
-    "sanitize_pty_command",
     "serve_command",
 ]

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/artifacts.py

@@ -5,8 +5,9 @@ Normal job completion is coordinated through small marker files inside each
 SQLite `exited(exit_code, ended_at)` state only after PTY output is fully
 drained into `output.log`. The same artifact directory also stores the request's
 environment overlay so the runner can merge arbitrary key/value pairs without
-shell-escaping them into the generated script. A separate failure marker is used
-so an unsuccessful sanitizer run does not masquerade as a drained normal exit.
+shell-escaping them into the generated script. Separate failure markers and a
+dedicated `pipe-error.log` stderr capture keep startup diagnostics available
+when the sanitizer never reaches its ready-file handshake.
 """
 
 from __future__ import annotations
@@ -18,6 +19,7 @@ RUNNER_ENDED_AT_FILENAME = ".runner-ended-at"
 JOB_ENV_FILENAME = ".job-env.json"
 PIPE_DRAINED_FILENAME = ".pipe-drained"
 PIPE_FAILED_FILENAME = ".pipe-failed"
+PIPE_ERROR_LOG_FILENAME = "pipe-error.log"
 
 
 def runner_exit_code_path(job_dir: Path) -> Path:
@@ -40,14 +42,20 @@ def pipe_failed_path(job_dir: Path) -> Path:
     return job_dir / PIPE_FAILED_FILENAME
 
 
+def pipe_error_log_path(job_dir: Path) -> Path:
+    return job_dir / PIPE_ERROR_LOG_FILENAME
+
+
 __all__ = [
     "JOB_ENV_FILENAME",
     "PIPE_DRAINED_FILENAME",
+    "PIPE_ERROR_LOG_FILENAME",
     "PIPE_FAILED_FILENAME",
     "RUNNER_ENDED_AT_FILENAME",
     "RUNNER_EXIT_CODE_FILENAME",
     "job_env_path",
     "pipe_drained_path",
+    "pipe_error_log_path",
     "pipe_failed_path",
     "runner_ended_at_path",
     "runner_exit_code_path",

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/cli.py

@@ -1,8 +1,13 @@
-"""Typer CLI entrypoints for shellctl server package."""
+"""Typer CLI entrypoints for the shellctl server package.
+
+The server CLI only exposes commands that need the FastAPI/SQLite runtime.
+The PTY sanitizer now lives in `shell_session_manager.shellctl.sanitize_pty`
+as a separate lightweight module so tmux pipes do not have a second, heavier
+entry path to maintain.
+"""
 
 from __future__ import annotations
 
-import sys
 from pathlib import Path
 
 import anyio
@@ -17,7 +22,6 @@ from shell_session_manager.shellctl.shared import (
     DEFAULT_GC_FINISHED_JOB_RETENTION_SECONDS,
     DEFAULT_GC_INTERVAL_SECONDS,
     default_state_dir,
-    sanitize_pty_stream,
 )
 
 cli = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False)
@@ -54,17 +58,6 @@ def serve_command(
     uvicorn.run(create_app(config), host=host, port=port, log_level="info")
 
 
-@cli.command("sanitize-pty")
-def sanitize_pty_command(
-    ready_file: Path | None = typer.Option(None, "--ready-file"),
-) -> None:
-    """Read raw PTY bytes from stdin and write sanitized UTF-8 text to stdout."""
-
-    if ready_file is not None:
-        ready_file.touch()
-    sanitize_pty_stream(sys.stdin.buffer, sys.stdout.buffer)
-
-
 @cli.command("runner-exit")
 def runner_exit_command(
     state_dir: Path = typer.Option(..., "--state-dir"),
@@ -107,6 +100,5 @@ __all__ = [
     "cli",
     "main",
     "runner_exit_command",
-    "sanitize_pty_command",
     "serve_command",
 ]

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/config.py

@@ -32,8 +32,10 @@ class ShellctlConfig:
     """Runtime configuration for the shellctl service and CLI.
 
     `shellctl_command` deliberately defaults to `python -m ...server` so the
-    tmux-side commands stay pinned to the same interpreter environment that
-    launched the API server.
+    tmux-side `runner-exit` callback stays pinned to the same interpreter
+    environment that launched the API server. `sanitize_pty_command` uses the
+    same interpreter but points at a lightweight module so the pipe ready-file
+    handshake does not pay FastAPI/SQLAlchemy import costs.
 
     Bearer auth is opt-in: if the explicit `auth_token` and the fallback
     `SHELLCTL_AUTH_TOKEN` environment variable are both missing or empty,
@@ -59,6 +61,7 @@ class ShellctlConfig:
     default_terminate_grace_seconds: float = DEFAULT_TERMINATE_GRACE_SECONDS
     poll_interval_seconds: float = 0.05
     pipe_monitor_interval_seconds: float = 1.0
+    pipe_ready_timeout_seconds: float = 10.0
     sqlite_busy_timeout_ms: int = 5000
     shellctl_command: tuple[str, ...] = field(
         default_factory=lambda: (
@@ -67,6 +70,13 @@ class ShellctlConfig:
             "shell_session_manager.shellctl.server",
         )
     )
+    sanitize_pty_command: tuple[str, ...] = field(
+        default_factory=lambda: (
+            sys.executable,
+            "-m",
+            "shell_session_manager.shellctl.sanitize_pty",
+        )
+    )
 
     def __post_init__(self) -> None:
         if self.runtime_dir is None:

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/service.py

@@ -30,6 +30,7 @@ from shell_session_manager.shellctl.server.artifacts import (
     RUNNER_EXIT_CODE_FILENAME,
     job_env_path,
     pipe_drained_path,
+    pipe_error_log_path,
     pipe_failed_path,
     runner_ended_at_path,
     runner_exit_code_path,
@@ -559,10 +560,10 @@ class ShellctlService:
     ) -> None:
         """Persist a drained normal-exit fact into SQLite.
 
-        The usual caller is the tmux pipe finalizer after `sanitize-pty` has
-        reached EOF and flushed `output.log`. `_materialize_status_view()` may
-        also call this as a recovery path when `.pipe-drained` plus the normal
-        exit metadata files exist but SQLite is still non-terminal. The
+        The usual caller is the tmux pipe finalizer after the lightweight PTY
+        sanitizer reaches EOF and flushes `output.log`. `_materialize_status_view()`
+        may also call this as a recovery path when `.pipe-drained` plus the
+        normal exit metadata files exist but SQLite is still non-terminal. The
         statement always records `exit_code` and `ended_at`, but it only changes
         `status` to `exited` when the current row is still non-terminal.
         """
@@ -635,13 +636,17 @@ class ShellctlService:
     async def _wait_for_output_pipe_ready(
         self, *, job_id: str, ready_file: Path
     ) -> None:
-        """Confirm the sanitize/output pipeline is live before opening start-gate."""
+        """Confirm the sanitize/output pipeline is live before opening start-gate.
 
-        deadline = anyio.current_time() + max(
-            self.config.poll_interval_seconds * 10,
-            self.config.pipe_monitor_interval_seconds,
-        )
+        Timeout failures include the ready-file path, current `#{pane_pipe}`
+        state, and a summary of `pipe-error.log` so operators can tell the
+        difference between slow startup, tmux pipe loss, and sanitizer crashes.
+        """
+
+        started_at = anyio.current_time()
+        deadline = started_at + self.config.pipe_ready_timeout_seconds
         while True:
+            waited_seconds = anyio.current_time() - started_at
             if ready_file.exists():
                 pipe_state = await self._tmux.is_output_pipe_active(job_id=job_id)
                 if pipe_state is True:
@@ -650,23 +655,87 @@ class ShellctlService:
                     raise ShellctlServerError(
                         500,
                         "pipe_failed",
-                        f"Output pipe never became ready for {job_id}",
+                        self._pipe_ready_failure_message(
+                            job_id=job_id,
+                            ready_file=ready_file,
+                            waited_seconds=waited_seconds,
+                            pipe_state=pipe_state,
+                            cause="tmux pane disappeared after the ready-file handshake",
+                        ),
                     )
             else:
                 if not await self._tmux.session_exists(job_session_name(job_id)):
+                    pipe_state = await self._tmux.is_output_pipe_active(job_id=job_id)
                     raise ShellctlServerError(
                         500,
                         "pipe_failed",
-                        f"Output pipe never became ready for {job_id}",
+                        self._pipe_ready_failure_message(
+                            job_id=job_id,
+                            ready_file=ready_file,
+                            waited_seconds=waited_seconds,
+                            pipe_state=pipe_state,
+                            cause="tmux session exited before the ready-file handshake",
+                        ),
                     )
             if anyio.current_time() >= deadline:
+                pipe_state = await self._tmux.is_output_pipe_active(job_id=job_id)
                 raise ShellctlServerError(
                     500,
                     "pipe_failed",
-                    f"Output pipe never became ready for {job_id}",
+                    self._pipe_ready_failure_message(
+                        job_id=job_id,
+                        ready_file=ready_file,
+                        waited_seconds=waited_seconds,
+                        pipe_state=pipe_state,
+                        cause="timed out waiting for the sanitize/output pipeline handshake",
+                    ),
                 )
             await anyio.sleep(self.config.poll_interval_seconds)
 
+    def _pipe_ready_failure_message(
+        self,
+        *,
+        job_id: str,
+        ready_file: Path,
+        waited_seconds: float,
+        pipe_state: bool | None,
+        cause: str,
+    ) -> str:
+        """Build a startup error message with enough pipe diagnostics to debug."""
+
+        return (
+            f"Output pipe never became ready for {job_id}: {cause}; "
+            f"waited {waited_seconds:.3f}s; "
+            f"ready-file={ready_file}; "
+            f"tmux #{{pane_pipe}}={self._format_pane_pipe_state(pipe_state)}; "
+            f"pipe-error.log={self._pipe_error_log_summary(ready_file.parent)}"
+        )
+
+    def _format_pane_pipe_state(self, pipe_state: bool | None) -> str:
+        if pipe_state is True:
+            return "1"
+        if pipe_state is False:
+            return "0"
+        return "pane-missing"
+
+    def _pipe_error_log_summary(self, job_dir: Path) -> str:
+        """Summarize sanitizer stderr without flooding API error responses."""
+
+        error_log = pipe_error_log_path(job_dir)
+        if not error_log.exists():
+            return f"{error_log} missing"
+        stderr_text = error_log.read_text(encoding="utf-8", errors="replace").strip()
+        if not stderr_text:
+            return f"{error_log} empty"
+        summary = " | ".join(
+            line.strip() for line in stderr_text.splitlines() if line.strip()
+        )
+        if not summary:
+            return f"{error_log} contains only whitespace"
+        if len(summary) > 240:
+            summary = f"{summary[:237]}..."
+        return f"{error_log}: {summary}"
+
     async def _materialize_status_view(
         self,
         job_id: str,

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/tmux.py

@@ -18,6 +18,7 @@ import anyio
 
 from shell_session_manager.shellctl.server.artifacts import (
     pipe_drained_path,
+    pipe_error_log_path,
     pipe_failed_path,
     runner_ended_at_path,
     runner_exit_code_path,
@@ -182,13 +183,14 @@ class TmuxController:
 
         For normal exits, the runner now records completion metadata into job
         artifacts and the pipe finalizer commits `runner-exit` only after
-        `sanitize-pty` reaches EOF and flushes `output.log` successfully.
+        the lightweight sanitizer reaches EOF and flushes `output.log`
+        successfully. Sanitizer stderr is captured into `pipe-error.log` so
+        startup timeouts can distinguish slow imports from subprocess crashes.
         """
 
         sanitize_command = self._shell_join(
             (
-                *self._config.shellctl_command,
-                "sanitize-pty",
+                *self._config.sanitize_pty_command,
                 "--ready-file",
                 str(ready_file),
             )
@@ -205,12 +207,13 @@ class TmuxController:
         )
         output_path = shlex.quote(str(job_dir / "output.log"))
         drained_path = shlex.quote(str(pipe_drained_path(job_dir)))
+        error_log_path = shlex.quote(str(pipe_error_log_path(job_dir)))
         failed_path = shlex.quote(str(pipe_failed_path(job_dir)))
         exit_code_path = shlex.quote(str(runner_exit_code_path(job_dir)))
         ended_at_path = shlex.quote(str(runner_ended_at_path(job_dir)))
         return " ; ".join(
             [
-                f"{sanitize_command} >> {output_path}",
+                f"{sanitize_command} >> {output_path} 2> {error_log_path}",
                 "sanitize_status=$?",
                 (
                     'if [ "$sanitize_status" -eq 0 ]; then '

{shell_session_manager-2.2.0 → shell_session_manager-2.2.1}/tests/test_shellctl_service.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import ast
 import importlib
 import json
 import os
@@ -29,10 +30,12 @@ from shell_session_manager.shellctl.server import (
 from shell_session_manager.shellctl.server.artifacts import (
     JOB_ENV_FILENAME,
     PIPE_DRAINED_FILENAME,
+    PIPE_ERROR_LOG_FILENAME,
     PIPE_FAILED_FILENAME,
     RUNNER_ENDED_AT_FILENAME,
     RUNNER_EXIT_CODE_FILENAME,
     job_env_path,
+    pipe_error_log_path,
 )
 from shell_session_manager.shellctl.server.tmux import TmuxController
 from shell_session_manager.shellctl.shared import (
@@ -57,6 +60,8 @@ class FakeTmuxController:
         self.pipe_active: dict[str, bool | None] = {}
         self.cleaned: list[str] = []
         self.touch_ready_on_enable = True
+        self.pipe_active_on_enable: bool | None = True
+        self.pipe_error_log_text: str | None = None
         self.on_send_interrupt: Callable[[str], Awaitable[None]] | None = None
         self.on_send_input: Callable[[str, str], Awaitable[None]] | None = None
 
@@ -82,8 +87,12 @@ class FakeTmuxController:
     async def enable_output_pipe(
         self, *, job_id: str, job_dir: Path, ready_file: Path
     ) -> None:
-        del job_dir
-        self.pipe_active[job_id] = True
+        self.pipe_active[job_id] = self.pipe_active_on_enable
+        if self.pipe_error_log_text is not None:
+            pipe_error_log_path(job_dir).write_text(
+                self.pipe_error_log_text,
+                encoding="utf-8",
+            )
         if self.touch_ready_on_enable:
             ready_file.touch()
 
@@ -122,15 +131,17 @@ async def _create_real_service(
     tmp_path: Path,
     *,
     shellctl_command: tuple[str, ...] | None = None,
+    sanitize_pty_command: tuple[str, ...] | None = None,
 ) -> ShellctlService:
+    defaults = ShellctlConfig(
+        state_dir=tmp_path / "default-state",
+        runtime_dir=tmp_path / "default-run",
+    )
     config = ShellctlConfig(
         state_dir=tmp_path / "state",
         runtime_dir=tmp_path / "run",
-        shellctl_command=shellctl_command
-        or ShellctlConfig(
-            state_dir=tmp_path / "default-state",
-            runtime_dir=tmp_path / "default-run",
-        ).shellctl_command,
+        shellctl_command=shellctl_command or defaults.shellctl_command,
+        sanitize_pty_command=sanitize_pty_command or defaults.sanitize_pty_command,
     )
     service = ShellctlService(config)
     await service.initialize()
@@ -154,9 +165,12 @@ def _write_delayed_sanitize_wrapper(
                 "import time",
                 "from pathlib import Path",
                 "",
-                f"REAL = [{sys.executable!r}, '-m', 'shell_session_manager.shellctl.server']",
+                (
+                    f"REAL = [{sys.executable!r}, '-m', "
+                    "'shell_session_manager.shellctl.sanitize_pty']"
+                ),
                 "args = sys.argv[1:]",
-                "if args[:1] == ['sanitize-pty'] and '--ready-file' in args:",
+                "if '--ready-file' in args:",
                 "    ready_file = Path(args[args.index('--ready-file') + 1])",
                 "    ready_file.touch()",
                 f"    time.sleep({delay_seconds!r})",
@@ -318,6 +332,12 @@ async def test_run_job_does_not_materialize_fresh_row_to_lost_during_startup_win
     await service.initialize_database()
     service._ensure_dir(service.config.jobs_dir)
     fake_tmux.touch_ready_on_enable = False
+    service.config = ShellctlConfig(
+        state_dir=service.config.state_dir,
+        runtime_dir=service.config.runtime_dir,
+        poll_interval_seconds=0.001,
+        pipe_ready_timeout_seconds=0.01,
+    )
 
     await service.run_job(
         RunJobRequest(
@@ -601,10 +621,10 @@ async def test_terminated_job_does_not_emit_python_wrapper_traceback(
 async def test_run_job_returns_flushed_output_on_first_terminal_result(
     tmp_path: Path,
 ) -> None:
-    shellctl_command = _write_delayed_sanitize_wrapper(tmp_path, delay_seconds=0.2)
+    sanitize_pty_command = _write_delayed_sanitize_wrapper(tmp_path, delay_seconds=0.2)
     service = await _create_real_service(
         tmp_path,
-        shellctl_command=shellctl_command,
+        sanitize_pty_command=sanitize_pty_command,
     )
 
     try:
@@ -644,14 +664,14 @@ async def test_run_job_returns_flushed_output_on_first_terminal_result(
 async def test_sanitize_failure_does_not_commit_normal_exit(
     tmp_path: Path,
 ) -> None:
-    shellctl_command = _write_delayed_sanitize_wrapper(
+    sanitize_pty_command = _write_delayed_sanitize_wrapper(
         tmp_path,
         delay_seconds=0.2,
         sanitize_exit_code=7,
     )
     service = await _create_real_service(
         tmp_path,
-        shellctl_command=shellctl_command,
+        sanitize_pty_command=sanitize_pty_command,
     )
 
     try:
@@ -1206,6 +1226,7 @@ async def test_run_job_keeps_start_gate_closed_when_pipe_never_becomes_ready(
         runtime_dir=service.config.runtime_dir,
         poll_interval_seconds=0.001,
         pipe_monitor_interval_seconds=0.01,
+        pipe_ready_timeout_seconds=0.01,
     )
 
     result = await service.run_job(
@@ -1225,6 +1246,43 @@ async def test_run_job_keeps_start_gate_closed_when_pipe_never_becomes_ready(
     await service.shutdown()
 
 
+@pytest.mark.anyio
+async def test_run_job_pipe_ready_timeout_records_diagnostics(tmp_path: Path) -> None:
+    service, fake_tmux = await _create_service(tmp_path)
+    fake_tmux.touch_ready_on_enable = False
+    fake_tmux.pipe_active_on_enable = False
+    fake_tmux.pipe_error_log_text = "Traceback: sanitizer crashed\nsecond line\n"
+    service.config = ShellctlConfig(
+        state_dir=service.config.state_dir,
+        runtime_dir=service.config.runtime_dir,
+        poll_interval_seconds=0.001,
+        pipe_ready_timeout_seconds=0.01,
+    )
+
+    result = await service.run_job(
+        RunJobRequest(
+            script="printf ready\n",
+            cwd=str(tmp_path),
+            terminal=TerminalSize(),
+            timeout=0.05,
+            output_limit=8192,
+            idle_flush_seconds=0.01,
+        )
+    )
+
+    row = await service._get_job_row(result.job_id)
+    ready_file = service.config.jobs_dir / result.job_id / ".pipe-ready"
+
+    assert result.status is JobStatusName.FAILED
+    assert row.message is not None
+    assert "waited " in row.message
+    assert str(ready_file) in row.message
+    assert "tmux #{pane_pipe}=0" in row.message
+    assert PIPE_ERROR_LOG_FILENAME in row.message
+    assert "Traceback: sanitizer crashed | second line" in row.message
+    await service.shutdown()
+
+
 @pytest.mark.anyio
 async def test_send_input_terminal_race_returns_conflict_not_500(
     tmp_path: Path,
@@ -1558,6 +1616,19 @@ def test_runner_script_records_completion_metadata_without_direct_runner_exit(
     anyio.run(service.shutdown)
 
 
+def test_shellctl_config_defaults_to_lightweight_sanitize_entrypoint(
+    tmp_path: Path,
+) -> None:
+    config = ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run")
+
+    assert config.pipe_ready_timeout_seconds == 10.0
+    assert config.sanitize_pty_command == (
+        sys.executable,
+        "-m",
+        "shell_session_manager.shellctl.sanitize_pty",
+    )
+
+
 def test_pipe_command_finalizer_commits_runner_exit_after_drain(tmp_path: Path) -> None:
     controller = TmuxController(
         ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run")
@@ -1568,17 +1639,88 @@ def test_pipe_command_finalizer_commits_runner_exit_after_drain(tmp_path: Path)
         ready_file=tmp_path / "state" / "jobs" / "05211530-k7p" / ".pipe-ready",
     )
 
-    assert "sanitize-pty" in source
+    assert "shell_session_manager.shellctl.sanitize_pty" in source
+    assert "shell_session_manager.shellctl.server sanitize-pty" not in source
     assert PIPE_DRAINED_FILENAME in source
+    assert PIPE_ERROR_LOG_FILENAME in source
     assert PIPE_FAILED_FILENAME in source
     assert RUNNER_EXIT_CODE_FILENAME in source
     assert RUNNER_ENDED_AT_FILENAME in source
     assert re.search(r"\brunner-exit\b", source) is not None
     assert 'if [ "$sanitize_status" -eq 0 ]' in source
-    assert source.index("sanitize-pty") < source.index(PIPE_DRAINED_FILENAME)
+    assert "2>" in source
+    assert source.index("shell_session_manager.shellctl.sanitize_pty") < source.index(
+        PIPE_DRAINED_FILENAME
+    )
     assert source.index(PIPE_DRAINED_FILENAME) < source.index("runner-exit")
 
 
+def test_sanitize_pty_module_uses_lightweight_imports_only() -> None:
+    module_path = (
+        Path(__file__).resolve().parents[1]
+        / "src"
+        / "shell_session_manager"
+        / "shellctl"
+        / "sanitize_pty.py"
+    )
+    tree = ast.parse(module_path.read_text(encoding="utf-8"))
+
+    imports: set[str] = set()
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import):
+            imports.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.module is not None:
+            imports.add(node.module)
+
+    assert imports == {
+        "argparse",
+        "pathlib",
+        "sys",
+        "shell_session_manager.shellctl.shared.sanitize",
+    }
+
+
+def test_python_m_sanitize_pty_module_touches_ready_file_and_sanitizes_output(
+    tmp_path: Path,
+) -> None:
+    package_root = Path(__file__).resolve().parents[1]
+    src_path = package_root / "src"
+    env = dict(os.environ)
+    current_pythonpath = env.get("PYTHONPATH")
+    env["PYTHONPATH"] = (
+        f"{src_path}{os.pathsep}{current_pythonpath}"
+        if current_pythonpath
+        else str(src_path)
+    )
+    ready_file = tmp_path / "ready"
+
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-m",
+            "shell_session_manager.shellctl.sanitize_pty",
+            "--ready-file",
+            str(ready_file),
+        ],
+        input=b"before\rafter\n",
+        capture_output=True,
+        check=False,
+        cwd=package_root,
+        env=env,
+    )
+
+    assert result.returncode == 0, result.stderr.decode("utf-8", errors="replace")
+    assert ready_file.exists()
+    assert result.stdout.decode("utf-8") == "after\n"
+
+
+def test_server_cli_no_longer_exposes_sanitize_pty_command() -> None:
+    result = CliRunner().invoke(cli, ["sanitize-pty"])
+
+    assert result.exit_code != 0
+    assert "No such command 'sanitize-pty'" in result.output
+
+
 def test_runner_exit_cli_accepts_runner_option_contract(tmp_path: Path) -> None:
     async def setup_running_job() -> ShellctlConfig:
         service, _fake_tmux = await _create_service(tmp_path)
@@ -1634,5 +1776,5 @@ def test_python_m_shellctl_server_module_entrypoint_shows_cli_help() -> None:
     )
 
     assert result.returncode == 0, result.stderr
-    assert "sanitize-pty" in result.stdout
+    assert "sanitize-pty" not in result.stdout
     assert "runner-exit" in result.stdout