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

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

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

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

{shell_session_manager-2.1.0 → shell_session_manager-2.2.0}/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.0/src/shell_session_manager/shellctl/server/artifacts.py

@@ -0,0 +1,54 @@
+"""Per-job artifact names used by shellctl server/runtime code.
+
+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`. 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.
+"""
+
+from __future__ import annotations
+
+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"
+
+
+def runner_exit_code_path(job_dir: Path) -> Path:
+    return job_dir / RUNNER_EXIT_CODE_FILENAME
+
+
+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
+
+
+def pipe_failed_path(job_dir: Path) -> Path:
+    return job_dir / PIPE_FAILED_FILENAME
+
+
+__all__ = [
+    "JOB_ENV_FILENAME",
+    "PIPE_DRAINED_FILENAME",
+    "PIPE_FAILED_FILENAME",
+    "RUNNER_ENDED_AT_FILENAME",
+    "RUNNER_EXIT_CODE_FILENAME",
+    "job_env_path",
+    "pipe_drained_path",
+    "pipe_failed_path",
+    "runner_ended_at_path",
+    "runner_exit_code_path",
+]

{shell_session_manager-2.1.0 → shell_session_manager-2.2.0}/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
@@ -23,6 +24,16 @@ from sqlalchemy.exc import IntegrityError
 from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
 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_failed_path,
+    runner_ended_at_path,
+    runner_exit_code_path,
+)
 from shell_session_manager.shellctl.server.config import ShellctlConfig
 from shell_session_manager.shellctl.server.db import JobRow, configure_sqlite_engine
 from shell_session_manager.shellctl.server.errors import ShellctlServerError
@@ -140,7 +151,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
@@ -160,6 +172,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,
@@ -175,6 +188,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,
@@ -540,9 +557,12 @@ class ShellctlService:
     async def record_runner_exit(
         self, job_id: str, exit_code: int, ended_at: str
     ) -> None:
-        """Persist the runner's exit fact into SQLite.
+        """Persist a drained normal-exit fact into SQLite.
 
-        This is the source-of-truth replacement for the old `exit.json`. The
+        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
         statement always records `exit_code` and `ended_at`, but it only changes
         `status` to `exited` when the current row is still non-terminal.
         """
@@ -660,6 +680,13 @@ class ShellctlService:
         - terminal SQLite status wins and is preserved
         - if SQLite already has an `exit_code` on a non-terminal row, materialize
           `exited`
+        - if normal-exit metadata and `.pipe-drained` already exist, recover the
+          drained normal exit immediately even when the finalizer has not yet
+          committed SQLite state
+        - if normal-exit metadata exists and neither `.pipe-drained` nor
+          `.pipe-failed` exists, keep the non-terminal row instead of guessing
+          `lost` while the pipe finalizer is still responsible for the eventual
+          `runner-exit` commit
         - if a live tmux session exists but the output pipe is known-dead,
           conditionally materialize `failed(reason=pipe_failed)`
         - if no live session exists and the row is not protected by the local
@@ -693,6 +720,10 @@ class ShellctlService:
                 target=JobStatusName.EXITED,
                 ended_at=row.ended_at or format_timestamp(),
             )
+        elif (drained_exit := self._drained_normal_exit_metadata(job_id)) is not None:
+            exit_code, ended_at = drained_exit
+            await self.record_runner_exit(job_id, exit_code, ended_at)
+            row = await self._get_job_row(job_id)
         elif session_exists:
             if pipe_active is False:
                 if (
@@ -728,7 +759,9 @@ class ShellctlService:
                     require_exit_code_null=True,
                 )
         else:
-            if not (
+            if self._normal_exit_commit_pending(job_id):
+                pass
+            elif not (
                 status in {JobStatusName.CREATED, JobStatusName.STARTING}
                 and job_id in self._starting_jobs
             ):
@@ -911,6 +944,36 @@ class ShellctlService:
     def _artifact_dir(self, job_id: str) -> Path:
         return self.config.jobs_dir / job_id
 
+    def _normal_exit_commit_pending(self, job_id: str) -> bool:
+        """Check whether a normal exit is still waiting for pipe drain + commit."""
+
+        job_dir = self._artifact_dir(job_id)
+        return (
+            runner_exit_code_path(job_dir).exists()
+            and runner_ended_at_path(job_dir).exists()
+            and not pipe_drained_path(job_dir).exists()
+            and not pipe_failed_path(job_dir).exists()
+        )
+
+    def _drained_normal_exit_metadata(self, job_id: str) -> tuple[int, str] | None:
+        """Read drained normal-exit metadata after successful sanitize drain."""
+
+        job_dir = self._artifact_dir(job_id)
+        drained_path = pipe_drained_path(job_dir)
+        exit_code_path = runner_exit_code_path(job_dir)
+        ended_at_path = runner_ended_at_path(job_dir)
+        if (
+            not drained_path.exists()
+            or not exit_code_path.exists()
+            or not ended_at_path.exists()
+        ):
+            return None
+        raw_exit_code = exit_code_path.read_text(encoding="utf-8").strip()
+        raw_ended_at = ended_at_path.read_text(encoding="utf-8").strip()
+        if not raw_exit_code or not raw_ended_at:
+            return None
+        return int(raw_exit_code), raw_ended_at
+
     def _allocate_job_dir(self) -> tuple[str, Path]:
         """Atomically allocate a unique artifact directory for a new job.
 
@@ -946,6 +1009,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:
@@ -968,11 +1042,58 @@ class ShellctlService:
         self.config.runner_path.chmod(mode | stat.S_IXUSR)
 
     def _runner_script_source(self) -> str:
-        tmux_socket = shlex.quote(str(self.config.tmux_socket))
-        state_dir = shlex.quote(str(self.config.state_dir))
+        """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)
-        shellctl_command = " ".join(
-            shlex.quote(part) for part in self.config.shellctl_command
+        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
@@ -981,7 +1102,18 @@ 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}"
+
+write_atomic() {{
+  local dest="$1"
+  local value="$2"
+  local tmp="${{dest}}.tmp.$$"
+  printf '%s\n' "$value" > "$tmp"
+  mv "$tmp" "$dest"
+}}
 
 while [ ! -e "$START_GATE" ]; do
   sleep 0.05
@@ -994,18 +1126,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
@@ -1013,8 +1135,9 @@ print(datetime.now(UTC).replace(microsecond=0).isoformat().replace('+00:00', 'Z'
 PY
 )"
 
-{shellctl_command} runner-exit --state-dir {state_dir} --job-id "$JOB_ID" --exit-code "$EXIT_CODE" --ended-at "$ENDED_AT"
-env -u TMUX tmux -S {tmux_socket} kill-session -t "shellctl-job-$JOB_ID" >/dev/null 2>&1 || true
+write_atomic "$RUNNER_EXIT_CODE_PATH" "$EXIT_CODE"
+write_atomic "$RUNNER_ENDED_AT_PATH" "$ENDED_AT"
+
 exit "$EXIT_CODE"
 """
 

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

@@ -16,6 +16,12 @@ from typing import Protocol, cast
 
 import anyio
 
+from shell_session_manager.shellctl.server.artifacts import (
+    pipe_drained_path,
+    pipe_failed_path,
+    runner_ended_at_path,
+    runner_exit_code_path,
+)
 from shell_session_manager.shellctl.server.config import ShellctlConfig
 from shell_session_manager.shellctl.server.errors import ShellctlServerError
 from shell_session_manager.shellctl.shared import (
@@ -148,16 +154,10 @@ class TmuxController:
     async def enable_output_pipe(
         self, *, job_id: str, job_dir: Path, ready_file: Path
     ) -> None:
-        sanitize_command = self._shell_join(
-            (
-                *self._config.shellctl_command,
-                "sanitize-pty",
-                "--ready-file",
-                str(ready_file),
-            )
-        )
-        output_command = (
-            f"{sanitize_command} >> {shlex.quote(str(job_dir / 'output.log'))}"
+        output_command = self._pipe_command_source(
+            job_id=job_id,
+            job_dir=job_dir,
+            ready_file=ready_file,
         )
         result = await self._run_tmux(
             "pipe-pane",
@@ -175,6 +175,55 @@ class TmuxController:
                 or f"Failed to attach output pipe for {job_id}",
             )
 
+    def _pipe_command_source(
+        self, *, job_id: str, job_dir: Path, ready_file: Path
+    ) -> str:
+        """Build the tmux `pipe-pane` command that drains and finalizes output.
+
+        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.
+        """
+
+        sanitize_command = self._shell_join(
+            (
+                *self._config.shellctl_command,
+                "sanitize-pty",
+                "--ready-file",
+                str(ready_file),
+            )
+        )
+        runner_exit_command = self._shell_join(
+            (
+                *self._config.shellctl_command,
+                "runner-exit",
+                "--state-dir",
+                str(self._config.state_dir),
+                "--job-id",
+                job_id,
+            )
+        )
+        output_path = shlex.quote(str(job_dir / "output.log"))
+        drained_path = shlex.quote(str(pipe_drained_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}",
+                "sanitize_status=$?",
+                (
+                    'if [ "$sanitize_status" -eq 0 ]; then '
+                    f": > {drained_path}; "
+                    f"if [ -s {exit_code_path} ] && [ -s {ended_at_path} ]; then "
+                    f'{runner_exit_command} --exit-code "$(cat {exit_code_path})" '
+                    f'--ended-at "$(cat {ended_at_path})"; fi; '
+                    f"else : > {failed_path}; fi"
+                ),
+                'exit "$sanitize_status"',
+            ]
+        )
+
     async def send_input(self, *, job_id: str, text: str) -> None:
         buffer_name = f"shellctl-in-{job_id}"
         runtime_dir = cast(Path, self._config.runtime_dir)
@@ -286,6 +335,7 @@ def _tmux_target_missing(stderr: str) -> bool:
         or "can't find session" in normalized
         or "no server running" in normalized
         or "failed to connect" in normalized
+        or "server exited unexpectedly" in normalized
     )
 
 

{shell_session_manager-2.1.0 → shell_session_manager-2.2.0}/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.0 → shell_session_manager-2.2.0}/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.0 → shell_session_manager-2.2.0}/tests/test_shellctl_service.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
 import importlib
+import json
 import os
+import re
+import shutil
 import sqlite3
 import subprocess
 import sys
@@ -23,6 +26,15 @@ from shell_session_manager.shellctl.server import (
     cli,
     create_app,
 )
+from shell_session_manager.shellctl.server.artifacts import (
+    JOB_ENV_FILENAME,
+    PIPE_DRAINED_FILENAME,
+    PIPE_FAILED_FILENAME,
+    RUNNER_ENDED_AT_FILENAME,
+    RUNNER_EXIT_CODE_FILENAME,
+    job_env_path,
+)
+from shell_session_manager.shellctl.server.tmux import TmuxController
 from shell_session_manager.shellctl.shared import (
     DEFAULT_AUTH_TOKEN_ENV,
     InputJobRequest,
@@ -106,6 +118,62 @@ async def _create_service(
     return service, fake_tmux
 
 
+async def _create_real_service(
+    tmp_path: Path,
+    *,
+    shellctl_command: tuple[str, ...] | None = None,
+) -> ShellctlService:
+    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,
+    )
+    service = ShellctlService(config)
+    await service.initialize()
+    return service
+
+
+def _write_delayed_sanitize_wrapper(
+    tmp_path: Path,
+    *,
+    delay_seconds: float,
+    sanitize_exit_code: int | None = None,
+) -> tuple[str, ...]:
+    wrapper_path = tmp_path / "delayed-sanitize-wrapper.py"
+    wrapper_path.write_text(
+        "\n".join(
+            [
+                "from __future__ import annotations",
+                "",
+                "import subprocess",
+                "import sys",
+                "import time",
+                "from pathlib import Path",
+                "",
+                f"REAL = [{sys.executable!r}, '-m', 'shell_session_manager.shellctl.server']",
+                "args = sys.argv[1:]",
+                "if args[:1] == ['sanitize-pty'] and '--ready-file' in args:",
+                "    ready_file = Path(args[args.index('--ready-file') + 1])",
+                "    ready_file.touch()",
+                f"    time.sleep({delay_seconds!r})",
+                (
+                    f"    raise SystemExit({sanitize_exit_code!r})"
+                    if sanitize_exit_code is not None
+                    else ""
+                ),
+                "raise SystemExit(subprocess.run(REAL + args, check=False).returncode)",
+                "",
+            ]
+        ),
+        encoding="utf-8",
+    )
+    return (sys.executable, str(wrapper_path))
+
+
 def _capture_serve_config(
     monkeypatch: pytest.MonkeyPatch,
 ) -> tuple[dict[str, object], CliRunner]:
@@ -287,6 +355,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,
@@ -307,6 +376,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
@@ -324,6 +397,373 @@ 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)
+    service = await _create_real_service(
+        tmp_path,
+        shellctl_command=shellctl_command,
+    )
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script="printf 'delayed-flush\\n'\n",
+                cwd=str(tmp_path),
+                terminal=TerminalSize(),
+                timeout=3,
+                output_limit=8192,
+                idle_flush_seconds=1,
+            )
+        )
+
+        reread = await service.wait_job(
+            result.job_id,
+            WaitJobRequest(
+                offset=0,
+                timeout=0.001,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            ),
+        )
+
+        assert result.done is True
+        assert result.status is JobStatusName.EXITED
+        assert result.exit_code == 0
+        assert result.output == "delayed-flush\n"
+        assert reread.output == "delayed-flush\n"
+        assert reread.offset == result.offset
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+async def test_sanitize_failure_does_not_commit_normal_exit(
+    tmp_path: Path,
+) -> None:
+    shellctl_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,
+    )
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script="printf 'missing-output\\n'\n",
+                cwd=str(tmp_path),
+                terminal=TerminalSize(),
+                timeout=3,
+                output_limit=8192,
+                idle_flush_seconds=1,
+            )
+        )
+
+        reread = await service.wait_job(
+            result.job_id,
+            WaitJobRequest(
+                offset=0,
+                timeout=0.001,
+                output_limit=8192,
+                idle_flush_seconds=0.01,
+            ),
+        )
+        job_dir = service.config.jobs_dir / result.job_id
+
+        assert result.done is True
+        assert result.status is not JobStatusName.EXITED
+        assert result.exit_code is None
+        assert result.output == ""
+        assert reread.output == ""
+        assert not (job_dir / PIPE_DRAINED_FILENAME).exists()
+        assert (job_dir / PIPE_FAILED_FILENAME).exists()
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+@pytest.mark.skipif(shutil.which("uv") is None, reason="uv is required")
+async def test_uv_quiet_shebang_returns_output_in_first_terminal_result(
+    tmp_path: Path,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script=(
+                    "#!/usr/bin/env -S uv run --script --quiet\n"
+                    "# /// script\n"
+                    '# requires-python = ">=3.12"\n'
+                    "# dependencies = []\n"
+                    "# ///\n"
+                    'print("hello")\n'
+                ),
+                cwd=str(tmp_path),
+                terminal=TerminalSize(),
+                timeout=10,
+                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 == "hello\n"
+    finally:
+        await service.shutdown()
+
+
+@pytest.mark.anyio
+@pytest.mark.skipif(shutil.which("tmux") is None, reason="tmux is required")
+@pytest.mark.skipif(shutil.which("bash") is None, reason="bash is required")
+@pytest.mark.parametrize(
+    ("script", "expected_output"),
+    [
+        ("printf 'no-shebang\\n'\n", "no-shebang\n"),
+        ("#!/bin/sh\nprintf 'sh-shebang\\n'\n", "sh-shebang\n"),
+        (
+            "#!/usr/bin/env bash\nprintf 'bash-shebang\\n'\n",
+            "bash-shebang\n",
+        ),
+    ],
+)
+async def test_existing_script_modes_still_return_output(
+    tmp_path: Path,
+    script: str,
+    expected_output: str,
+) -> None:
+    service = await _create_real_service(tmp_path)
+
+    try:
+        result = await service.run_job(
+            RunJobRequest(
+                script=script,
+                cwd=str(tmp_path),
+                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 == expected_output
+    finally:
+        await service.shutdown()
+
+
 @pytest.mark.anyio
 async def test_run_job_retries_after_sqlite_insert_conflict_and_cleans_artifacts(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
@@ -557,6 +997,32 @@ async def test_session_disappearing_between_probes_materializes_lost_not_pipe_fa
     await service.shutdown()
 
 
+@pytest.mark.anyio
+async def test_drained_uncommitted_normal_exit_self_commits_to_exited(
+    tmp_path: Path,
+) -> None:
+    service, _fake_tmux = await _create_service(tmp_path)
+    job_id = "05211530-k7p"
+    await _seed_job(service, job_id=job_id, status=JobStatusName.RUNNING)
+    job_dir = service.config.jobs_dir / job_id
+    (job_dir / RUNNER_EXIT_CODE_FILENAME).write_text("0\n", encoding="utf-8")
+    (job_dir / RUNNER_ENDED_AT_FILENAME).write_text(
+        "2026-05-21T15:30:20Z\n", encoding="utf-8"
+    )
+    (job_dir / PIPE_DRAINED_FILENAME).touch()
+
+    view = await service.get_job_status(job_id)
+    row = await service._get_job_row(job_id)
+
+    assert view.status is JobStatusName.EXITED
+    assert view.done is True
+    assert view.exit_code == 0
+    assert row.status == JobStatusName.EXITED.value
+    assert row.exit_code == 0
+    assert row.ended_at == "2026-05-21T15:30:20Z"
+    await service.shutdown()
+
+
 @pytest.mark.anyio
 async def test_list_jobs_ignores_half_created_directory_and_uses_db_rows(
     tmp_path: Path,
@@ -1074,6 +1540,45 @@ def test_serve_cli_reads_auth_token_from_environment(
     assert config.auth_token == "env-token"
 
 
+def test_runner_script_records_completion_metadata_without_direct_runner_exit(
+    tmp_path: Path,
+) -> None:
+    service = ShellctlService(
+        ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run"),
+        tmux=FakeTmuxController(),
+    )
+    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
+    assert 'mv "$tmp" "$dest"' in source
+    assert re.search(r"\brunner-exit\s+--state-dir\b", source) is None
+    anyio.run(service.shutdown)
+
+
+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")
+    )
+    source = controller._pipe_command_source(
+        job_id="05211530-k7p",
+        job_dir=tmp_path / "state" / "jobs" / "05211530-k7p",
+        ready_file=tmp_path / "state" / "jobs" / "05211530-k7p" / ".pipe-ready",
+    )
+
+    assert "sanitize-pty" in source
+    assert PIPE_DRAINED_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 source.index(PIPE_DRAINED_FILENAME) < source.index("runner-exit")
+
+
 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)

{shell_session_manager-2.1.0 → shell_session_manager-2.2.0}/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)