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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shell-session-manager
-Version: 2.1.1
+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.1.1 → shell_session_manager-2.2.1}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "shell-session-manager"
-version = "2.1.1"
+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.1.1 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/client/sdk.py

@@ -96,14 +96,20 @@ class ShellctlClient:
         script: str,
         *,
         cwd: str | None = None,
+        env: dict[str, str] | None = None,
         timeout: float = DEFAULT_TIMEOUT_SECONDS,
         terminal: TerminalSize | None = None,
     ) -> JobResult:
-        """Create a new job and wait for initial output or completion."""
+        """Create a new job and wait for initial output or completion.
+
+        `cwd` and `env` preset the script's working directory and environment
+        overlay on the server side.
+        """
 
         payload = RunJobRequest(
             script=script,
             cwd=cwd,
+            env=env,
             terminal=terminal,
             timeout=timeout,
             output_limit=self.output_limit,

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.1.1 → 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.1.1 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/artifacts.py

@@ -3,8 +3,11 @@
 Normal job completion is coordinated through small marker files inside each
 `jobs/<job_id>/` directory so the tmux output-pipe finalizer can publish the
 SQLite `exited(exit_code, ended_at)` state only after PTY output is fully
-drained into `output.log`. A separate failure marker is used so an unsuccessful
-sanitizer run does not masquerade as a drained normal exit.
+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. 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
@@ -13,8 +16,10 @@ from pathlib import Path
 
 RUNNER_EXIT_CODE_FILENAME = ".runner-exit-code"
 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:
@@ -25,6 +30,10 @@ def runner_ended_at_path(job_dir: Path) -> Path:
     return job_dir / RUNNER_ENDED_AT_FILENAME
 
 
+def job_env_path(job_dir: Path) -> Path:
+    return job_dir / JOB_ENV_FILENAME
+
+
 def pipe_drained_path(job_dir: Path) -> Path:
     return job_dir / PIPE_DRAINED_FILENAME
 
@@ -33,12 +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.1.1 → 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.1.1 → 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.1.1 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/server/service.py

@@ -9,6 +9,7 @@ This module owns the long-lived job lifecycle rules: artifact creation,
 from __future__ import annotations
 
 import asyncio
+import json
 import shlex
 import shutil
 import stat
@@ -24,9 +25,12 @@ from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_asyn
 from sqlmodel import SQLModel
 
 from shell_session_manager.shellctl.server.artifacts import (
+    JOB_ENV_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,
@@ -148,7 +152,8 @@ class ShellctlService:
         """Create a tmux-backed job and wait for its initial result window.
 
         Side effects:
-        - allocates `jobs/<job_id>/` and writes `script` / `output.log`
+        - allocates `jobs/<job_id>/` and writes `script`, `.job-env.json`, and
+          `output.log`
         - inserts a `jobs` row into SQLite, then conditionally transitions it
           through `created -> starting -> running`
         - creates a dedicated tmux session, installs `pipe-pane`, waits for the
@@ -168,6 +173,7 @@ class ShellctlService:
         """
 
         cwd = self._resolve_cwd(request.cwd)
+        env = self._resolve_env(request.env)
         terminal = request.terminal or TerminalSize(
             cols=self.config.default_terminal_cols,
             rows=self.config.default_terminal_rows,
@@ -183,6 +189,10 @@ class ShellctlService:
                 script_path = candidate_job_dir / "script"
                 output_path = candidate_job_dir / "output.log"
                 script_path.write_text(request.script, encoding="utf-8")
+                job_env_path(candidate_job_dir).write_text(
+                    json.dumps(env, ensure_ascii=False),
+                    encoding="utf-8",
+                )
                 output_path.touch()
                 row = JobRow(
                     job_id=candidate_job_id,
@@ -550,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.
         """
@@ -626,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:
@@ -641,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,
@@ -1000,6 +1078,17 @@ class ShellctlService:
             )
         return cwd
 
+    def _resolve_env(self, raw_env: dict[str, str] | None) -> dict[str, str]:
+        """Return a detached environment overlay for the generated runner.
+
+        `RunJobRequest` validates names/values before the service sees them.
+        The overlay augments the runner's inherited environment after shellctl
+        scrubs its own control variables, so explicit request values can be used
+        without replacing ambient entries like `PATH`.
+        """
+
+        return dict(raw_env or {})
+
     def _validate_offset(self, output_path: Path, offset: int) -> None:
         size = output_path.stat().st_size if output_path.exists() else 0
         if offset > size:
@@ -1022,7 +1111,59 @@ class ShellctlService:
         self.config.runner_path.chmod(mode | stat.S_IXUSR)
 
     def _runner_script_source(self) -> str:
+        """Build the bash runner installed into the shellctl runtime directory.
+
+        The wrapper still handles gate waiting and exit metadata in bash, but it
+        delegates launch setup to Python so per-job env overlays can be loaded
+        from JSON without shell-escaping arbitrary values into `export`
+        statements. The Python helper then `exec`s the target process instead of
+        waiting on it, which keeps `SIGINT` behavior identical to running the
+        script directly in the tmux pane. The bootstrap uses `python -c ...`
+        instead of a stdin-fed heredoc so the exec'd job still inherits the tmux
+        pane's PTY on fd 0 and can receive later `send_input()` data.
+        """
+
         auth_env = shlex.quote(DEFAULT_AUTH_TOKEN_ENV)
+        bootstrap_source = shlex.quote(
+            """
+import json
+import os
+import stat
+import sys
+from pathlib import Path
+
+script_path = Path(sys.argv[1])
+cwd = sys.argv[2]
+env_path = Path(sys.argv[3])
+
+env = os.environ.copy()
+if env_path.exists():
+    env.update(json.loads(env_path.read_text(encoding="utf-8")))
+
+try:
+    os.chdir(cwd)
+except OSError:
+    raise SystemExit(111)
+
+with script_path.open("r", encoding="utf-8") as handle:
+    first_line = handle.readline()
+
+if first_line.startswith("#!"):
+    script_path.chmod(script_path.stat().st_mode | stat.S_IXUSR)
+    argv = [str(script_path)]
+else:
+    argv = ["sh", str(script_path)]
+
+try:
+    os.execvpe(argv[0], argv, env)
+except FileNotFoundError as exc:
+    print(f"{argv[0]}: {exc.strerror}", file=sys.stderr)
+    raise SystemExit(127) from exc
+except OSError as exc:
+    print(f"{argv[0]}: {exc.strerror}", file=sys.stderr)
+    raise SystemExit(126) from exc
+            """.strip()
+        )
         return f"""#!/usr/bin/env bash
 set -uo pipefail
 
@@ -1030,6 +1171,7 @@ JOB_DIR="$1"
 JOB_ID="$2"
 CWD="$3"
 SCRIPT_PATH="$JOB_DIR/script"
+ENV_PATH="$JOB_DIR/{JOB_ENV_FILENAME}"
 START_GATE="$JOB_DIR/start-gate"
 RUNNER_EXIT_CODE_PATH="$JOB_DIR/{RUNNER_EXIT_CODE_FILENAME}"
 RUNNER_ENDED_AT_PATH="$JOB_DIR/{RUNNER_ENDED_AT_FILENAME}"
@@ -1053,18 +1195,8 @@ unset SHELLCTL_TMUX_SOCKET
 unset SHELLCTL_RUNNER
 unset {auth_env}
 
-if cd "$CWD"; then
-  if IFS= read -r FIRST_LINE < "$SCRIPT_PATH" && [[ "$FIRST_LINE" == '#!'* ]]; then
-    chmod +x "$SCRIPT_PATH"
-    "$SCRIPT_PATH"
-    EXIT_CODE=$?
-  else
-    sh "$SCRIPT_PATH"
-    EXIT_CODE=$?
-  fi
-else
-  EXIT_CODE=111
-fi
+{shlex.quote(sys.executable)} -c {bootstrap_source} "$SCRIPT_PATH" "$CWD" "$ENV_PATH"
+EXIT_CODE=$?
 
 ENDED_AT="$({shlex.quote(sys.executable)} - <<'PY'
 from datetime import UTC, datetime

{shell_session_manager-2.1.1 → 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.1.1 → shell_session_manager-2.2.1}/src/shell_session_manager/shellctl/shared/schemas.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from enum import StrEnum
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from shell_session_manager.shellctl.shared.constants import (
     DEFAULT_HEALTH_STATUS,
@@ -128,10 +128,16 @@ class ErrorResponse(ShellctlModel):
 
 
 class RunJobRequest(ShellctlModel):
-    """HTTP request body for `POST /v1/jobs/run`."""
+    """HTTP request body for `POST /v1/jobs/run`.
+
+    `env` augments the runner's inherited process environment instead of
+    replacing it, so callers can preset script-local variables without losing
+    ambient values such as `PATH`.
+    """
 
     script: str
     cwd: str | None = None
+    env: dict[str, str] | None = None
     terminal: TerminalSize | None = None
     timeout: float = Field(
         default=DEFAULT_TIMEOUT_SECONDS, gt=0, le=MAX_WAIT_TIMEOUT_SECONDS
@@ -141,6 +147,30 @@ class RunJobRequest(ShellctlModel):
     )
     idle_flush_seconds: float = Field(default=DEFAULT_IDLE_FLUSH_SECONDS, ge=0, le=30)
 
+    @field_validator("env")
+    @classmethod
+    def _validate_env(cls, env: dict[str, str] | None) -> dict[str, str] | None:
+        """Reject env entries that cannot be represented in `execve`.
+
+        shellctl applies `env` as a process environment overlay, so validation
+        follows the low-level `NAME=value` constraints instead of shell variable
+        naming rules: names must be non-empty and cannot contain `=` or NUL,
+        while values cannot contain NUL.
+        """
+
+        if env is None:
+            return None
+        for name, value in env.items():
+            if not name:
+                raise ValueError("env names must be non-empty")
+            if "=" in name:
+                raise ValueError(f"env name must not contain '=': {name!r}")
+            if "\x00" in name:
+                raise ValueError(f"env name must not contain NUL: {name!r}")
+            if "\x00" in value:
+                raise ValueError(f"env value must not contain NUL: {name!r}")
+        return env
+
 
 class WaitJobRequest(ShellctlModel):
     """HTTP request body for `POST /v1/jobs/{job_id}/wait`."""

{shell_session_manager-2.1.1 → shell_session_manager-2.2.1}/tests/test_shellctl_client.py

@@ -39,7 +39,12 @@ async def test_shellctl_client_run_injects_headers_and_instance_defaults(
         idle_flush_seconds=0.25,
         transport=transport,
     ) as client:
-        await client.run("printf ready\\n", cwd="/tmp", timeout=12)
+        await client.run(
+            "printf ready\\n",
+            cwd="/tmp",
+            env={"HELLO": "world"},
+            timeout=12,
+        )
 
     assert captured["method"] == "POST"
     assert captured["path"] == "/v1/jobs/run"
@@ -47,6 +52,7 @@ async def test_shellctl_client_run_injects_headers_and_instance_defaults(
     assert captured["json"] == {
         "script": "printf ready\\n",
         "cwd": "/tmp",
+        "env": {"HELLO": "world"},
         "timeout": 12.0,
         "output_limit": 4096,
         "idle_flush_seconds": 0.25,

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

@@ -1,6 +1,8 @@
 from __future__ import annotations
 
+import ast
 import importlib
+import json
 import os
 import re
 import shutil
@@ -26,10 +28,14 @@ from shell_session_manager.shellctl.server import (
     create_app,
 )
 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 (
@@ -54,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
 
@@ -79,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()
 
@@ -119,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()
@@ -151,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})",
@@ -315,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(
@@ -352,6 +375,7 @@ async def test_run_job_happy_path_persists_running_row_and_artifacts(
         RunJobRequest(
             script="printf ready\n",
             cwd=str(tmp_path),
+            env={"HELLO": "world", "UNICODE": "盐粒"},
             terminal=TerminalSize(cols=100, rows=40),
             timeout=0.01,
             output_limit=8192,
@@ -372,6 +396,10 @@ async def test_run_job_happy_path_persists_running_row_and_artifacts(
     assert row.output_path == f"jobs/{result.job_id}/output.log"
     assert row.started_at is not None
     assert (job_dir / "script").exists()
+    assert json.loads(job_env_path(job_dir).read_text(encoding="utf-8")) == {
+        "HELLO": "world",
+        "UNICODE": "盐粒",
+    }
     assert (job_dir / "output.log").exists()
     assert (job_dir / "start-gate").exists()
     assert job_session_name(result.job_id) in fake_tmux.sessions
@@ -389,15 +417,214 @@ async def test_run_job_happy_path_persists_running_row_and_artifacts(
     await service.shutdown()
 
 
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_run_job_env_overlay_is_visible_without_replacing_inherited_env(
+    tmp_path: Path,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "python3 - <<'PY'\n"
+                    "import os\n"
+                    "print(os.environ['SHELLCTL_PRESET'])\n"
+                    "print('PATH' in os.environ)\n"
+                    "PY\n"
+                ),
+                cwd=str(tmp_path),
+                env={"SHELLCTL_PRESET": "from-client"},
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=1,
+            )
+        )
+
+        assert result.done is True
+        assert result.status is JobStatusName.EXITED
+        assert result.exit_code == 0
+        assert result.output == "from-client\nTrue\n"
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_run_job_env_overlay_overrides_inherited_value(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    monkeypatch.setenv("SHELLCTL_PRESET", "parent")
+    service = await _create_real_service(tmp_path)
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "python3 - <<'PY'\n"
+                    "import os\n"
+                    "print(os.environ['SHELLCTL_PRESET'])\n"
+                    "PY\n"
+                ),
+                cwd=str(tmp_path),
+                env={"SHELLCTL_PRESET": "from-client"},
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=1,
+            )
+        )
+
+        assert result.done is True
+        assert result.status is JobStatusName.EXITED
+        assert result.exit_code == 0
+        assert result.output == "from-client\n"
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_send_input_reaches_real_job_stdin_after_env_bootstrap(
+    tmp_path: Path,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        initial = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "printf 'ready\\n'\n"
+                    "IFS= read -r line\n"
+                    "printf 'got:%s\\n' \"$line\"\n"
+                ),
+                cwd=str(tmp_path),
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            )
+        )
+
+        ready_window = initial
+        if ready_window.output == "":
+            ready_window = await service.wait_job(
+                initial.job_id,
+                WaitJobRequest(
+                    offset=initial.offset,
+                    timeout=1,
+                    output_limit=8192,
+                    idle_flush_seconds=0.01,
+                ),
+            )
+
+        result = await service.send_input(
+            initial.job_id,
+            InputJobRequest(
+                text="hello from stdin\n",
+                offset=ready_window.offset,
+                timeout=1,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            ),
+        )
+
+        output_after_input = result.output
+        final = result
+        if not final.done:
+            # `send_input()` shares wait semantics with `wait_job()`: it may
+            # return after the post-input output flushes but before tmux exit
+            # artifacts have materialized into a terminal DB status on slower CI.
+            final = await service.wait_job(
+                initial.job_id,
+                WaitJobRequest(
+                    offset=result.offset,
+                    timeout=5,
+                    output_limit=8192,
+                    idle_flush_seconds=0.01,
+                ),
+            )
+            output_after_input += final.output
+
+        assert ready_window.done is False
+        assert final.done is True
+        assert final.status is JobStatusName.EXITED
+        assert final.exit_code == 0
+        assert output_after_input.endswith("got:hello from stdin\n")
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_terminated_job_does_not_emit_python_wrapper_traceback(
+    tmp_path: Path,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        initial = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "trap 'exit 130' INT\n"
+                    "printf 'ready\\n'\n"
+                    "while :; do sleep 1; done\n"
+                ),
+                cwd=str(tmp_path),
+                terminal=TerminalSize(),
+                timeout=5,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            )
+        )
+
+        ready_window = initial
+        if ready_window.output == "":
+            ready_window = await service.wait_job(
+                initial.job_id,
+                WaitJobRequest(
+                    offset=initial.offset,
+                    timeout=1,
+                    output_limit=8192,
+                    idle_flush_seconds=0.01,
+                ),
+            )
+        assert ready_window.done is False
+
+        terminated = await service.terminate_job(
+            initial.job_id,
+            TerminateJobRequest(grace_seconds=0.2),
+        )
+        final = await service.wait_job(
+            initial.job_id,
+            WaitJobRequest(
+                offset=ready_window.offset,
+                timeout=1,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            ),
+        )
+
+        assert terminated.status is JobStatusName.TERMINATED
+        assert final.done is True
+        assert "KeyboardInterrupt" not in final.output
+        assert "Traceback (most recent call last)" not in final.output
+    finally:
+        await service.shutdown()
+
+
 @pytest.mark.anyio
 @pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
 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:
@@ -437,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:
@@ -999,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(
@@ -1018,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,
@@ -1342,6 +1607,7 @@ def test_runner_script_records_completion_metadata_without_direct_runner_exit(
     )
     source = service._runner_script_source()
 
+    assert JOB_ENV_FILENAME in source
     assert RUNNER_EXIT_CODE_FILENAME in source
     assert RUNNER_ENDED_AT_FILENAME in source
     assert "write_atomic" in source
@@ -1350,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")
@@ -1360,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)
@@ -1426,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

{shell_session_manager-2.1.1 → shell_session_manager-2.2.1}/tests/test_shellctl_shared.py

@@ -4,9 +4,13 @@ from datetime import UTC, datetime
 from io import BytesIO
 from pathlib import Path
 
+import pytest
+from pydantic import ValidationError
+
 from shell_session_manager.shellctl.shared import (
     JOB_ID_ALPHABET,
     PtySanitizer,
+    RunJobRequest,
     generate_job_id,
     read_output_window,
     sanitize_pty_output,
@@ -112,3 +116,19 @@ def test_sanitize_pty_stream_flushes_incrementally() -> None:
 
     assert stdout.getvalue() == b"ready\nnext\n"
     assert stdout.flush_count >= 2
+
+
+@pytest.mark.parametrize(
+    ("env", "message"),
+    [
+        ({"": "x"}, "non-empty"),
+        ({"A=B": "x"}, "must not contain '='"),
+        ({"A\x00B": "x"}, "must not contain NUL"),
+        ({"A": "x\x00y"}, "must not contain NUL"),
+    ],
+)
+def test_run_job_request_rejects_invalid_env_entries(
+    env: dict[str, str], message: str
+) -> None:
+    with pytest.raises(ValidationError, match=message):
+        RunJobRequest(script="printf ready\n", env=env)