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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: shell-session-manager
-Version: 2.0.0
+Version: 2.1.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
@@ -67,3 +67,16 @@ async def main() -> None:
 
 anyio.run(main)
 ```
+
+## shellctl server
+
+Run the HTTP API locally with:
+
+```bash
+pdm run shellctl serve --listen 127.0.0.1:8765
+```
+
+Pass `--auth-token your-token` when you want bearer auth enforced. `shellctl
+serve` also reads `SHELLCTL_AUTH_TOKEN`, so you can export the token instead of
+passing the flag. Leave the flag/env var unset or empty to start without
+requiring an Authorization header.

{shell_session_manager-2.0.0 → shell_session_manager-2.1.1}/README.md

@@ -49,3 +49,16 @@ async def main() -> None:
 
 anyio.run(main)
 ```
+
+## shellctl server
+
+Run the HTTP API locally with:
+
+```bash
+pdm run shellctl serve --listen 127.0.0.1:8765
+```
+
+Pass `--auth-token your-token` when you want bearer auth enforced. `shellctl
+serve` also reads `SHELLCTL_AUTH_TOKEN`, so you can export the token instead of
+passing the flag. Leave the flag/env var unset or empty to start without
+requiring an Authorization header.

{shell_session_manager-2.0.0 → shell_session_manager-2.1.1}/pyproject.toml

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

{shell_session_manager-2.0.0 → shell_session_manager-2.1.1}/src/shell_session_manager/shellctl/server/api.py

@@ -88,7 +88,10 @@ def create_app(
     def verify_auth(
         authorization: Annotated[str | None, Header()] = None,
     ) -> None:
-        expected = f"Bearer {resolved_config.auth_token}"
+        token = resolved_config.auth_token
+        if token is None:
+            return
+        expected = f"Bearer {token}"
         if authorization != expected:
             raise ShellctlServerError(
                 401, "unauthorized", "Missing or invalid bearer token"

shell_session_manager-2.1.1/src/shell_session_manager/shellctl/server/artifacts.py

@@ -0,0 +1,45 @@
+"""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`. 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"
+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 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__ = [
+    "PIPE_DRAINED_FILENAME",
+    "PIPE_FAILED_FILENAME",
+    "RUNNER_ENDED_AT_FILENAME",
+    "RUNNER_EXIT_CODE_FILENAME",
+    "pipe_drained_path",
+    "pipe_failed_path",
+    "runner_ended_at_path",
+    "runner_exit_code_path",
+]

{shell_session_manager-2.0.0 → shell_session_manager-2.1.1}/src/shell_session_manager/shellctl/server/cli.py

@@ -26,7 +26,15 @@ cli = typer.Typer(no_args_is_help=True, pretty_exceptions_enable=False)
 @cli.command("serve")
 def serve_command(
     listen: str = "127.0.0.1:8765",
-    auth_token_env: str = DEFAULT_AUTH_TOKEN_ENV,
+    auth_token: str | None = typer.Option(
+        None,
+        "--auth-token",
+        envvar=DEFAULT_AUTH_TOKEN_ENV,
+        help=(
+            "Bearer token value. You can also set SHELLCTL_AUTH_TOKEN. "
+            "Leave it unset or empty to disable HTTP bearer auth."
+        ),
+    ),
     state_dir: Path | None = None,
     runtime_dir: Path | None = None,
     gc_interval_seconds: float = DEFAULT_GC_INTERVAL_SECONDS,
@@ -37,7 +45,7 @@ def serve_command(
     host, port = _parse_listen(listen)
     config = ShellctlConfig(
         listen=listen,
-        auth_token_env=auth_token_env,
+        auth_token=auth_token,
         state_dir=state_dir or default_state_dir(),
         runtime_dir=runtime_dir,
         gc_interval_seconds=gc_interval_seconds,

{shell_session_manager-2.0.0 → shell_session_manager-2.1.1}/src/shell_session_manager/shellctl/server/config.py

@@ -34,10 +34,14 @@ class ShellctlConfig:
     `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.
+
+    Bearer auth is opt-in: if the explicit `auth_token` and the fallback
+    `SHELLCTL_AUTH_TOKEN` environment variable are both missing or empty,
+    `shellctl serve` accepts requests without checking an Authorization header.
     """
 
     listen: str = "127.0.0.1:8765"
-    auth_token_env: str = DEFAULT_AUTH_TOKEN_ENV
+    auth_token: str | None = None
     state_dir: Path = field(default_factory=default_state_dir)
     runtime_dir: Path | None = None
     gc_interval_seconds: float = DEFAULT_GC_INTERVAL_SECONDS
@@ -67,6 +71,12 @@ class ShellctlConfig:
     def __post_init__(self) -> None:
         if self.runtime_dir is None:
             object.__setattr__(self, "runtime_dir", default_runtime_dir(self.state_dir))
+        token = self.auth_token
+        if token is None:
+            token = os.environ.get(DEFAULT_AUTH_TOKEN_ENV)
+        if not token:
+            token = None
+        object.__setattr__(self, "auth_token", token)
 
     @property
     def jobs_dir(self) -> Path:
@@ -90,14 +100,5 @@ class ShellctlConfig:
         runtime_dir = cast(Path, self.runtime_dir)
         return runtime_dir / "bin" / "shellctl-runner"
 
-    @property
-    def auth_token(self) -> str:
-        token = os.environ.get(self.auth_token_env)
-        if not token:
-            raise RuntimeError(
-                f"Missing bearer token in environment variable {self.auth_token_env}"
-            )
-        return token
-
 
 __all__ = ["ShellctlConfig"]

{shell_session_manager-2.0.0 → shell_session_manager-2.1.1}/src/shell_session_manager/shellctl/server/service.py

@@ -23,6 +23,14 @@ 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 (
+    RUNNER_ENDED_AT_FILENAME,
+    RUNNER_EXIT_CODE_FILENAME,
+    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
@@ -31,6 +39,7 @@ from shell_session_manager.shellctl.server.tmux import (
     TmuxControllerProtocol,
 )
 from shell_session_manager.shellctl.shared import (
+    DEFAULT_AUTH_TOKEN_ENV,
     DeleteJobResponse,
     InputJobRequest,
     JobInfo,
@@ -97,9 +106,12 @@ class ShellctlService:
             await connection.run_sync(SQLModel.metadata.create_all)
 
     async def initialize(self) -> None:
-        """Prepare directories, database, runner script, and tmux state."""
+        """Prepare directories, database, runner script, and tmux state.
+
+        Auth is configured at the API layer, so service startup must also work
+        when `shellctl serve` is intentionally running without a bearer token.
+        """
 
-        _ = self.config.auth_token
         await self.initialize_database()
         self._ensure_dir(cast(Path, self.config.runtime_dir))
         self._ensure_dir(self.config.jobs_dir)
@@ -536,9 +548,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.
         """
@@ -656,6 +671,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
@@ -689,6 +711,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 (
@@ -724,7 +750,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
             ):
@@ -907,6 +935,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.
 
@@ -964,12 +1022,7 @@ 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))
-        auth_env = shlex.quote(self.config.auth_token_env)
-        shellctl_command = " ".join(
-            shlex.quote(part) for part in self.config.shellctl_command
-        )
+        auth_env = shlex.quote(DEFAULT_AUTH_TOKEN_ENV)
         return f"""#!/usr/bin/env bash
 set -uo pipefail
 
@@ -978,6 +1031,16 @@ JOB_ID="$2"
 CWD="$3"
 SCRIPT_PATH="$JOB_DIR/script"
 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
@@ -1009,8 +1072,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.0.0 → shell_session_manager-2.1.1}/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.0.0 → shell_session_manager-2.1.1}/tests/test_shellctl_service.py

@@ -1,6 +1,9 @@
 from __future__ import annotations
 
+import importlib
 import os
+import re
+import shutil
 import sqlite3
 import subprocess
 import sys
@@ -22,7 +25,15 @@ from shell_session_manager.shellctl.server import (
     cli,
     create_app,
 )
+from shell_session_manager.shellctl.server.artifacts import (
+    PIPE_DRAINED_FILENAME,
+    PIPE_FAILED_FILENAME,
+    RUNNER_ENDED_AT_FILENAME,
+    RUNNER_EXIT_CODE_FILENAME,
+)
+from shell_session_manager.shellctl.server.tmux import TmuxController
 from shell_session_manager.shellctl.shared import (
+    DEFAULT_AUTH_TOKEN_ENV,
     InputJobRequest,
     JobStatusName,
     JobStatusView,
@@ -34,6 +45,8 @@ from shell_session_manager.shellctl.shared import (
     job_session_name,
 )
 
+server_cli_module = importlib.import_module("shell_session_manager.shellctl.server.cli")
+
 
 class FakeTmuxController:
     def __init__(self) -> None:
@@ -85,10 +98,16 @@ class FakeTmuxController:
         self.pipe_active.pop(job_id, None)
 
 
-async def _create_service(tmp_path: Path) -> tuple[ShellctlService, FakeTmuxController]:
+async def _create_service(
+    tmp_path: Path, *, auth_token: str | None = None
+) -> tuple[ShellctlService, FakeTmuxController]:
     fake_tmux = FakeTmuxController()
     service = ShellctlService(
-        ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run"),
+        ShellctlConfig(
+            auth_token=auth_token,
+            state_dir=tmp_path / "state",
+            runtime_dir=tmp_path / "run",
+        ),
         tmux=fake_tmux,
     )
     await service.initialize_database()
@@ -96,6 +115,82 @@ async def _create_service(tmp_path: Path) -> tuple[ShellctlService, FakeTmuxCont
     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]:
+    captured: dict[str, object] = {}
+
+    def fake_create_app(config: ShellctlConfig):
+        captured["config"] = config
+        return object()
+
+    def fake_run(app: object, *, host: str, port: int, log_level: str) -> None:
+        captured["app"] = app
+        captured["host"] = host
+        captured["port"] = port
+        captured["log_level"] = log_level
+
+    monkeypatch.setattr(server_cli_module, "create_app", fake_create_app)
+    monkeypatch.setattr(server_cli_module.uvicorn, "run", fake_run)
+    return captured, CliRunner()
+
+
 async def _seed_job(
     service: ShellctlService,
     *,
@@ -294,6 +389,174 @@ 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_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
@@ -527,6 +790,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,
@@ -788,12 +1077,24 @@ async def test_allocate_job_dir_retries_on_atomic_mkdir_collision(
     await service.shutdown()
 
 
+@pytest.mark.anyio
+async def test_service_initialize_allows_missing_auth_token(tmp_path: Path) -> None:
+    service = ShellctlService(
+        ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run"),
+        tmux=FakeTmuxController(),
+    )
+
+    await service.initialize()
+
+    assert service.config.runner_path.exists()
+    await service.shutdown()
+
+
 @pytest.mark.anyio
 async def test_http_routes_inject_shellctl_service_dependency(
-    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    tmp_path: Path,
 ) -> None:
-    monkeypatch.setenv("SHELLCTL_AUTH_TOKEN", "route-token")
-    service, _fake_tmux = await _create_service(tmp_path)
+    service, _fake_tmux = await _create_service(tmp_path, auth_token="route-token")
     app = create_app(service.config, service=service)
     transport = httpx.ASGITransport(app=app)
 
@@ -815,6 +1116,261 @@ async def test_http_routes_inject_shellctl_service_dependency(
     await service.shutdown()
 
 
+@pytest.mark.anyio
+async def test_http_routes_enforce_auth_from_environment_fallback(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "route-token")
+    service, _fake_tmux = await _create_service(tmp_path)
+    app = create_app(service.config, service=service)
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        unauthenticated = await client.get("/v1/jobs")
+        authenticated = await client.get(
+            "/v1/jobs", headers={"Authorization": "Bearer route-token"}
+        )
+
+    assert unauthenticated.status_code == 401
+    assert authenticated.status_code == 200
+    await service.shutdown()
+
+
+@pytest.mark.anyio
+async def test_create_app_without_explicit_config_reads_auth_token_from_environment(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    async def noop_initialize(self: ShellctlService) -> None:
+        return None
+
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "route-token")
+    monkeypatch.setattr(ShellctlService, "initialize", noop_initialize)
+    monkeypatch.setattr(ShellctlService, "start_background_gc", lambda self: None)
+    monkeypatch.setattr(
+        ShellctlService, "start_background_pipe_monitor", lambda self: None
+    )
+
+    app = create_app()
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        response = await client.get("/v1/jobs")
+
+    assert app.state.shellctl_service.config.auth_token == "route-token"
+    assert response.status_code == 401
+    await app.state.shellctl_service.shutdown()
+
+
+@pytest.mark.anyio
+async def test_http_routes_skip_auth_when_token_missing(tmp_path: Path) -> None:
+    service, _fake_tmux = await _create_service(tmp_path)
+    app = create_app(service.config, service=service)
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        response = await client.get("/v1/jobs")
+
+    assert response.status_code == 200
+    assert response.json() == {"jobs": []}
+    await service.shutdown()
+
+
+@pytest.mark.anyio
+async def test_http_routes_skip_auth_when_token_is_empty(tmp_path: Path) -> None:
+    service, _fake_tmux = await _create_service(tmp_path, auth_token="")
+    app = create_app(service.config, service=service)
+    transport = httpx.ASGITransport(app=app)
+
+    async with httpx.AsyncClient(
+        transport=transport, base_url="http://shellctl.test"
+    ) as client:
+        response = await client.get("/v1/jobs")
+
+    assert response.status_code == 200
+    assert response.json() == {"jobs": []}
+    await service.shutdown()
+
+
+def test_shellctl_config_reads_auth_token_from_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+
+    config = ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run")
+
+    assert config.auth_token == "env-token"
+
+
+def test_shellctl_config_treats_empty_environment_auth_token_as_disabled(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "")
+
+    config = ShellctlConfig(state_dir=tmp_path / "state", runtime_dir=tmp_path / "run")
+
+    assert config.auth_token is None
+
+
+def test_serve_cli_passes_direct_auth_token_to_config(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--listen",
+            "0.0.0.0:9999",
+            "--auth-token",
+            "direct-token",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    assert captured["host"] == "0.0.0.0"
+    assert captured["port"] == 9999
+    assert captured["log_level"] == "info"
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token == "direct-token"
+
+
+def test_serve_cli_prefers_explicit_auth_token_over_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--auth-token",
+            "direct-token",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token == "direct-token"
+
+
+def test_serve_cli_treats_empty_auth_token_as_disabled(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--auth-token",
+            "",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token is None
+
+
+def test_serve_cli_explicit_empty_auth_token_beats_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--auth-token",
+            "",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    assert config.auth_token is None
+
+
+def test_serve_cli_reads_auth_token_from_environment(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    monkeypatch.setenv(DEFAULT_AUTH_TOKEN_ENV, "env-token")
+    captured, runner = _capture_serve_config(monkeypatch)
+
+    result = runner.invoke(
+        cli,
+        [
+            "serve",
+            "--state-dir",
+            str(tmp_path / "state"),
+        ],
+    )
+
+    assert result.exit_code == 0, result.output
+    config = captured["config"]
+    assert isinstance(config, ShellctlConfig)
+    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 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)