pocketshell 0.4.0__tar.gz → 0.4.1__tar.gz

{pocketshell-0.4.0 → pocketshell-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.4.0
+Version: 0.4.1
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues

{pocketshell-0.4.0 → pocketshell-0.4.1}/pyproject.toml

@@ -8,7 +8,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
 # runs that check before publishing to PyPI. See
 # tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.4.0"
+version = "0.4.1"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

{pocketshell-0.4.0 → pocketshell-0.4.1}/src/pocketshell/agent_log.py

@@ -129,6 +129,36 @@ def _encode_claude_cwd(cwd: str) -> str:
     return trimmed.replace("/", "-")
 
 
+def _is_within(path: Path, root: Path) -> bool:
+    """True when ``path`` is ``root`` or a descendant, after resolving both.
+
+    Mirrors ``prune_attachments._is_within`` / the ``repos.safe_clone_target``
+    containment pattern used elsewhere in this package. Both sides are
+    ``resolve()``-d first so a legitimately symlinked HOME (e.g. ``/home`` ->
+    ``/data/home``) does not falsely trip the guard — only genuine traversal
+    *out* of the per-engine root is rejected.
+    """
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def _contained_candidate(candidate: Path, root: Path) -> Optional[Path]:
+    """Return ``candidate`` only if it is a regular file inside ``root``.
+
+    The single choke point that closes the ``--session`` / ``--cwd`` path
+    traversal (#774 §2): an app-supplied name carrying ``..`` segments or an
+    absolute component is rejected because the resolved candidate escapes the
+    per-engine log root. ``.jsonl`` suffix + "is a regular file" remain
+    necessary but are no longer the *only* fence.
+    """
+    if not _is_within(candidate, root):
+        return None
+    return candidate if candidate.is_file() else None
+
+
 def _ensure_jsonl_suffix(session: str) -> str:
     """Append ``.jsonl`` if the caller passed a bare session id.
 
@@ -157,15 +187,16 @@ def _resolve_claude_path(session: str, cwd: Optional[str]) -> Optional[Path]:
     root = _claude_projects_root()
     if cwd is not None:
         candidate = root / _encode_claude_cwd(cwd) / filename
-        return candidate if candidate.is_file() else None
+        return _contained_candidate(candidate, root)
     if not root.is_dir():
         return None
     for project_dir in sorted(root.iterdir()):
         if not project_dir.is_dir():
             continue
         candidate = project_dir / filename
-        if candidate.is_file():
-            return candidate
+        contained = _contained_candidate(candidate, root)
+        if contained is not None:
+            return contained
     return None
 
 
@@ -182,10 +213,12 @@ def _resolve_codex_path(session: str) -> Optional[Path]:
         return None
     # ``Path.rglob`` returns matches in directory-walk order; the codex
     # tree is shallow (year/month/day/file) so this is cheap even with
-    # months of history.
+    # months of history. A ``..``-laden session name can make rglob surface
+    # a traversal path, so each candidate is still containment-checked.
     for candidate in root.rglob(filename):
-        if candidate.is_file():
-            return candidate
+        contained = _contained_candidate(candidate, root)
+        if contained is not None:
+            return contained
     return None
 
 
@@ -201,7 +234,7 @@ def _resolve_opencode_path(session: str) -> Optional[Path]:
     if not root.is_dir():
         return None
     candidate = root / filename
-    return candidate if candidate.is_file() else None
+    return _contained_candidate(candidate, root)
 
 
 def _resolve_log_path(

{pocketshell-0.4.0 → pocketshell-0.4.1}/src/pocketshell/agents.py

@@ -73,6 +73,7 @@ from __future__ import annotations
 
 import json
 import os
+import shutil
 from pathlib import Path
 from typing import Optional
 
@@ -327,6 +328,21 @@ def seed_claude_trust(config_path: Path, directory: str) -> None:
 # ---------------------------------------------------------------------------
 
 
+def _agent_missing_message(kind: str) -> str:
+    """Friendly install hint shown when the agent CLI is not on PATH.
+
+    Mirrors the missing-binary wording used by ``pocketshell.sessions`` /
+    ``pocketshell.usage`` / ``pocketshell.jobs`` so the user sees a
+    consistent ``127`` + install-hint message whichever subcommand
+    surfaces the failure first, instead of a raw ``FileNotFoundError``
+    traceback from ``os.execvpe``.
+    """
+    return (
+        f"pocketshell: `{kind}` is not installed on this host (not on PATH). "
+        f"Install the {kind} CLI and re-run."
+    )
+
+
 def _resolve_dir(ctx: click.Context, directory: str) -> Path:
     """Expand ``directory`` and require it to be an existing folder."""
     path = Path(os.path.expanduser(directory))
@@ -377,6 +393,16 @@ def launch_agent(
     )
     argv = build_argv(kind, skip_permissions=skip_permissions)
 
+    # Preflight: confirm the agent CLI is on PATH *before* os.chdir + exec.
+    # Without this, a missing `claude`/`codex`/`opencode` makes os.execvpe
+    # raise FileNotFoundError and dump a raw Python traceback to the SSH
+    # client. Emit the same friendly 127 + install hint every other
+    # subcommand uses instead (#774 §3).
+    if shutil.which(argv[0]) is None:
+        click.echo(_agent_missing_message(kind), err=True)
+        ctx.exit(127)
+        return
+
     # Run from the folder so the agent's cwd is correct.
     os.chdir(resolved_dir)
 

{pocketshell-0.4.0 → pocketshell-0.4.1}/src/pocketshell/daemon.py

@@ -61,6 +61,7 @@ import subprocess
 import sys
 import threading
 import time
+import traceback
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any, Callable, Mapping, Optional
@@ -836,12 +837,20 @@ class Daemon:
                 data=exc.data,
             )
             return
-        except Exception as exc:  # noqa: BLE001 — JSON-RPC envelope
+        except Exception:  # noqa: BLE001 — JSON-RPC envelope
+            # Log the full traceback (type, message, host paths) to the
+            # daemon's OWN stderr for operator debugging, but return only
+            # a generic, detail-free message over the socket. The raw
+            # ``str(exc)`` can embed internal filesystem paths / config
+            # values; even on the same-user SSH trust boundary there is no
+            # reason to surface those to the peer. The method name is the
+            # only request-correlatable hint the client gets.
+            traceback.print_exc(file=sys.stderr)
             self._send_error(
                 client_sock,
                 request_id=request_id,
                 code=JSONRPC_INTERNAL_ERROR,
-                message=f"{type(exc).__name__}: {exc}",
+                message=f"internal error handling {method!r}",
             )
             return
 

{pocketshell-0.4.0 → pocketshell-0.4.1}/src/pocketshell/jobs.py

@@ -64,7 +64,9 @@ verbs). Instead:
 - `start`  invokes `tmuxctl jobs daemon` in the foreground (passes
            through `--poll-interval` and `--run-once`).
 - `status` uses `pgrep -f` to detect a running daemon process.
-- `stop`   uses `pkill -TERM -f` to signal the running daemon.
+- `stop`   resolves the daemon PID(s) with `pgrep -f`, re-validates
+           each candidate's argv, then sends SIGTERM via `os.kill` to
+           exactly those PIDs (never a blunt `pkill -f`).
 
 Per the daemon-mode spike (linked from the brief) `tmuxctl jobs
 daemon` is a *scheduler loop*, not an IPC daemon. A separate
@@ -76,26 +78,132 @@ refactor the scheduler.
 
 from __future__ import annotations
 
+import os
 import shutil
+import signal
 import subprocess
 import sys
+from pathlib import Path
 from typing import Any, Optional, Sequence
 
 import click
 
-# Regex passed to `pgrep -f` / `pkill -f`. We anchor on `tmuxctl` being
-# preceded by either start-of-line or a path separator so the pattern
-# matches a real `…/tmuxctl jobs daemon …` invocation but does NOT
-# match an interactive shell whose argv contains the *substring*
+# Regex passed to `pgrep -f` to *find candidate* PIDs. We anchor on
+# `tmuxctl` being preceded by either start-of-line or a path separator
+# so the pattern matches a real `…/tmuxctl jobs daemon …` invocation but
+# does NOT match an interactive shell whose argv contains the *substring*
 # `tmuxctl jobs daemon` (e.g. an editor or another shell typing the
 # command). The trailing `( |$)` keeps us from matching
 # `tmuxctl jobs daemon-something-else` if such a verb ever appears.
+#
+# This regex is only the *first* filter. `pgrep -f` (and the old
+# `pkill -f`) match the pattern against the whole space-joined command
+# line, so a coincidental argv — e.g. `vim notes/tmuxctl jobs daemon.md`
+# — can still match. Before sending any signal we therefore re-validate
+# each candidate's actual argv vector via `_argv_is_daemon` so we only
+# ever signal a process whose argv genuinely *is* a `tmuxctl jobs daemon`
+# invocation. That makes `daemon stop` precise instead of a blunt
+# `pkill -f` that signals every matching command line on the host.
 _DAEMON_PROCESS_PATTERN = r"(^|/)tmuxctl jobs daemon( |$)"
 # Plain substring used only for human-facing diagnostics; never passed
 # to a process-matching tool.
 _DAEMON_HUMAN_LABEL = "tmuxctl jobs daemon"
 
 
+def _read_proc_argv(pid: int) -> Optional[list[str]]:
+    """Return the argv vector for ``pid`` from ``/proc/<pid>/cmdline``.
+
+    The cmdline pseudo-file is NUL-separated argv with a trailing NUL.
+    Returns ``None`` when the process is gone, unreadable, or the host
+    has no ``/proc`` (non-Linux) — callers treat ``None`` as "cannot
+    confirm this PID is the daemon" and skip it rather than guessing.
+    """
+    try:
+        raw = Path("/proc", str(pid), "cmdline").read_bytes()
+    except (OSError, ValueError):
+        return None
+    if not raw:
+        return None
+    parts = raw.split(b"\x00")
+    # A trailing NUL leaves an empty final element; drop empties.
+    return [p.decode("utf-8", "replace") for p in parts if p]
+
+
+def _argv_is_daemon(argv: Sequence[str]) -> bool:
+    """True iff ``argv`` is literally a ``tmuxctl jobs daemon`` invocation.
+
+    This inspects the discrete argv *vector* (not a joined string), so a
+    file path or buffer that merely *contains* the substring
+    ``tmuxctl jobs daemon`` cannot match: we require argv[0]'s basename to
+    be exactly ``tmuxctl`` (optionally a `python …/tmuxctl` shim) followed
+    by the ``jobs`` and ``daemon`` subcommand tokens as their own argv
+    elements.
+    """
+    tokens = list(argv)
+    if not tokens:
+        return False
+
+    # Skip a leading interpreter (`python`, `python3`, …) so a
+    # `python /usr/bin/tmuxctl jobs daemon` launch still matches on the
+    # tmuxctl token rather than the interpreter.
+    idx = 0
+    first = os.path.basename(tokens[0])
+    if first in ("python", "python3") or first.startswith("python3."):
+        idx = 1
+
+    if idx >= len(tokens):
+        return False
+    if os.path.basename(tokens[idx]) != "tmuxctl":
+        return False
+    rest = tokens[idx + 1 :]
+    return len(rest) >= 2 and rest[0] == "jobs" and rest[1] == "daemon"
+
+
+def _resolve_daemon_pids() -> list[int]:
+    """Resolve the PIDs of live `tmuxctl jobs daemon` processes, validated.
+
+    Uses `pgrep -f` as the cheap first pass to enumerate candidate PIDs,
+    then confirms each candidate's real argv with :func:`_argv_is_daemon`
+    so coincidental command-line matches are dropped. Our own PID is
+    always excluded. Returns ``[]`` when `pgrep` is unavailable or no
+    genuine daemon is running.
+    """
+    pgrep_path = shutil.which("pgrep")
+    if pgrep_path is None:
+        return []
+    completed = subprocess.run(
+        [pgrep_path, "-f", _DAEMON_PROCESS_PATTERN],
+        check=False,
+        capture_output=True,
+        text=True,
+    )
+    if completed.returncode not in (0, 1):
+        # pgrep error (>=2): surface as "no resolvable PIDs" and let the
+        # caller decide. We do not signal anything on an enumeration error.
+        return []
+
+    own_pid = os.getpid()
+    pids: list[int] = []
+    for line in completed.stdout.split():
+        try:
+            pid = int(line)
+        except ValueError:
+            continue
+        if pid == own_pid:
+            continue
+        argv = _read_proc_argv(pid)
+        if argv is None:
+            # No /proc (non-Linux) — fall back to trusting pgrep's match
+            # so the feature still works off-Linux, but only when we could
+            # not read argv at all, never to widen a readable mismatch.
+            if not Path("/proc").exists():
+                pids.append(pid)
+            continue
+        if _argv_is_daemon(argv):
+            pids.append(pid)
+    return pids
+
+
 def _resolve_tmuxctl_binary() -> Optional[str]:
     """Locate the `tmuxctl` CLI on PATH, or return ``None`` if absent.
 
@@ -609,8 +717,10 @@ def _is_daemon_running() -> bool:
     help=(
         "Control the tmuxctl recurring-jobs scheduler.\n\n"
         "`start` runs `tmuxctl jobs daemon` in the foreground; `status` "
-        "and `stop` query/signal the running process via pgrep/pkill. The "
-        "scheduler loop and SQLite database remain owned by `tmuxctl`."
+        "and `stop` query/signal the running process via `pgrep` + argv "
+        "validation (stop sends SIGTERM only to the resolved daemon PIDs, "
+        "not a blunt `pkill -f`). The scheduler loop and SQLite database "
+        "remain owned by `tmuxctl`."
     ),
 )
 def daemon_group() -> None:
@@ -682,33 +792,46 @@ def daemon_status(ctx: click.Context) -> None:
 def daemon_stop(ctx: click.Context) -> None:
     """Signal a running `tmuxctl jobs daemon` to terminate.
 
-    Uses `pkill -TERM -f` so SIGTERM is delivered to every matching
-    scheduler process. If no daemon is running we exit 0 (idempotent
-    stop), matching `systemctl stop` semantics for an already-stopped
-    unit.
+    Resolves the daemon's PID(s) with `pgrep -f`, re-validates each
+    candidate's actual argv vector (so a coincidental command line that
+    merely *contains* the pattern is never signalled), then delivers
+    SIGTERM directly via :func:`os.kill` to exactly those PIDs. This
+    replaces the old blunt `pkill -TERM -f`, which signalled *every*
+    process whose full command line matched the pattern. If no daemon is
+    running we exit 0 (idempotent stop), matching `systemctl stop`
+    semantics for an already-stopped unit.
     """
-    pkill_path = shutil.which("pkill")
-    if pkill_path is None:
+    if shutil.which("pgrep") is None:
         click.echo(
-            "pocketshell: `pkill` is not available on this host; cannot "
+            "pocketshell: `pgrep` is not available on this host; cannot "
             "stop the scheduler.",
             err=True,
         )
         ctx.exit(127)
-    completed = subprocess.run(
-        [pkill_path, "-TERM", "-f", _DAEMON_PROCESS_PATTERN],
-        check=False,
-        capture_output=True,
-        text=True,
-    )
-    # pkill exit codes: 0 = signalled at least one, 1 = no match,
-    # others = error. Treat "no match" as a successful idempotent stop.
-    if completed.returncode == 0:
-        click.echo("stopped")
-        return
-    if completed.returncode == 1:
+
+    pids = _resolve_daemon_pids()
+    if not pids:
         click.echo("not running")
         return
-    if completed.stderr:
-        sys.stderr.write(completed.stderr)
-    ctx.exit(completed.returncode)
+
+    signalled = 0
+    for pid in pids:
+        try:
+            os.kill(pid, signal.SIGTERM)
+        except ProcessLookupError:
+            # Raced with the process exiting between resolve and kill;
+            # treat as already gone.
+            continue
+        except PermissionError as exc:
+            sys.stderr.write(
+                f"pocketshell: cannot signal pid {pid}: {exc}\n"
+            )
+            continue
+        signalled += 1
+
+    if signalled:
+        click.echo("stopped")
+        return
+    # We found candidate PIDs but every one vanished or was unsignalable;
+    # the daemon is effectively not running anymore.
+    click.echo("not running")

{pocketshell-0.4.0 → pocketshell-0.4.1}/src/pocketshell/qr_share.py

@@ -132,7 +132,10 @@ def _resolve_with_ssh_config(alias: str) -> dict:
 def _read_private_key(path: pathlib.Path) -> str:
     if not path.exists():
         raise click.ClickException(f"key file not found: {path}")
-    return path.read_text().strip()
+    pem = path.read_text().strip()
+    if not pem:
+        raise click.ClickException(f"private key file is empty: {path}")
+    return pem
 
 
 def build_payload(

{pocketshell-0.4.0 → pocketshell-0.4.1}/tests/test_agent_log.py

@@ -658,3 +658,160 @@ def test_engine_choice_is_case_insensitive(fake_home: Path) -> None:
     assert result.exit_code == 0, result.output
     expected = "".join(json.dumps(e, sort_keys=True) + "\n" for e in events)
     assert result.output == expected
+
+
+# ----- path-traversal containment (issue #774 §2) --------------------
+#
+# `--session` / `--cwd` are app-supplied over SSH. Before #774 the raw
+# value was joined straight into a Path, so a `..`-laden session or cwd
+# escaped the per-engine log root and `agent-log` could `tail` any
+# `*.jsonl`-suffixed file the host user could read. These tests pin the
+# containment guard: a traversal MUST NOT resolve to a file outside the
+# intended root, even when that file physically exists.
+#
+# Each test plants a REAL secret `.jsonl` at the exact location the
+# unguarded resolver would escape to (outside the per-engine root but
+# inside the hermetic `fake_home` tmp dir), so on the unfixed code the
+# resolver genuinely returns it (red) and after the fix it is contained
+# (green).
+
+
+def _write_secret_jsonl(path: Path) -> Path:
+    """Create a real `.jsonl` exfil target at ``path``."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text('{"role": "user", "text": "TOP-SECRET"}\n', encoding="utf-8")
+    return path
+
+
+def test_claude_session_traversal_with_cwd_is_rejected(fake_home: Path) -> None:
+    """`--cwd /x --session ../../../escape` must not escape the root.
+
+    From `<home>/.claude/projects/-x/`, three `../` segments climb back to
+    `<home>` (== fake_home), where a real secret is planted. The unguarded
+    resolver returns it; the guard must refuse.
+    """
+    # The encoded-cwd project dir must physically exist so the literal
+    # (unresolved) `..` path is reachable by `is_file()`.
+    proj = fake_home / ".claude" / "projects" / "-x"
+    proj.mkdir(parents=True)
+    secret = _write_secret_jsonl(fake_home / "escape.jsonl")
+    traversal = "../../../escape"  # lands at <home>/escape.jsonl
+
+    # Demonstrate the file is genuinely reachable by raw path-join (so the
+    # guard, not a missing file, is what blocks it).
+    raw = proj / f"{traversal}.jsonl"
+    assert raw.resolve() == secret.resolve()
+    assert raw.is_file()
+
+    assert agent_log_module._resolve_claude_path(traversal, "/x") is None
+
+    runner = CliRunner()
+    result = runner.invoke(
+        agent_log_command,
+        ["--engine", "claude", "--session", traversal, "--cwd", "/x"],
+    )
+    assert result.exit_code == 66, result.output
+    assert "TOP-SECRET" not in result.output
+
+
+def test_claude_session_traversal_without_cwd_is_rejected(fake_home: Path) -> None:
+    """The no-`--cwd` scan path joins the raw session under each project
+    dir; a `..` chain must be refused there too.
+    """
+    # A real project dir must exist for the scan loop to iterate.
+    proj = fake_home / ".claude" / "projects" / "-real"
+    proj.mkdir(parents=True)
+    secret = _write_secret_jsonl(fake_home / "escape2.jsonl")
+    # From <home>/.claude/projects/-real/, three ../ reach <home>.
+    traversal = "../../../escape2"
+    raw = proj / f"{traversal}.jsonl"
+    assert raw.resolve() == secret.resolve() and raw.is_file()
+
+    assert agent_log_module._resolve_claude_path(traversal, None) is None
+
+
+def test_codex_session_traversal_is_rejected(fake_home: Path) -> None:
+    """Codex `rglob`s its tree by the session filename; a `..`-laden name
+    still resolves to a traversal path, so it must be contained.
+    """
+    sessions = fake_home / ".codex" / "sessions"
+    sessions.mkdir(parents=True)
+    secret = _write_secret_jsonl(fake_home / "codexescape.jsonl")
+    # From <home>/.codex/sessions/, two ../ reach <home>.
+    traversal = "../../codexescape"
+    # rglob genuinely surfaces the traversal target on the unfixed code.
+    matches = list(sessions.rglob(f"{traversal}.jsonl"))
+    assert matches and matches[0].resolve() == secret.resolve()
+
+    assert agent_log_module._resolve_codex_path(traversal) is None
+
+
+def test_opencode_session_traversal_is_rejected(fake_home: Path) -> None:
+    """OpenCode joins `--session` directly under its root; a `..` chain
+    must not escape `~/.local/share/opencode/`.
+    """
+    root = fake_home / ".local" / "share" / "opencode"
+    root.mkdir(parents=True)
+    secret = _write_secret_jsonl(fake_home / "ocescape.jsonl")
+    # From <home>/.local/share/opencode/, three ../ reach <home>.
+    traversal = "../../../ocescape"
+    raw = root / f"{traversal}.jsonl"
+    assert raw.resolve() == secret.resolve() and raw.is_file()
+
+    assert agent_log_module._resolve_opencode_path(traversal) is None
+
+
+def test_claude_cwd_traversal_is_rejected(fake_home: Path) -> None:
+    """A `..`-laden `--cwd` must not escape the projects root.
+
+    `_encode_claude_cwd` only rewrites `/` -> `-`, leaving `..` segments
+    intact, so an unguarded `--cwd` chain `resolve()`s above the root.
+    """
+    # encoded cwd "-..-..-..-.." => projects/-..-..-..-../<session>.jsonl
+    secret = _write_secret_jsonl(fake_home / ".claude" / "viacwd.jsonl")
+    # cwd "/../../../.." encodes to "-..-..-..-..": from projects/ that dir
+    # walks up to <home>/.claude where the secret sits.
+    resolved = agent_log_module._resolve_claude_path("viacwd", "/../../../..")
+    # On the unfixed code this could surface the planted secret; the guard
+    # must return None.
+    assert resolved is None
+    assert secret.is_file()
+
+
+def test_absolute_session_is_rejected(fake_home: Path, tmp_path: Path) -> None:
+    """An absolute `--session` path must be refused for every engine.
+
+    `Path(root) / "/etc/foo.jsonl"` discards `root` entirely in pathlib,
+    so without a guard an absolute session reads straight off the host fs.
+    """
+    outside = tmp_path.parent / "abs_secret.jsonl"
+    secret = _write_secret_jsonl(outside)
+    abs_session = str(secret)  # absolute, ends in .jsonl, real file
+    assert secret.is_file()
+    assert agent_log_module._resolve_claude_path(abs_session, "/x") is None
+    assert agent_log_module._resolve_codex_path(abs_session) is None
+    assert agent_log_module._resolve_opencode_path(abs_session) is None
+
+
+def test_legitimate_session_through_symlinked_home_still_resolves(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A real home reached via a symlink must still resolve (top risk a).
+
+    The containment check `resolve()`s both sides, so a symlinked home
+    does not falsely trip the guard for a legitimate in-root session.
+    """
+    real_home = tmp_path / "real_home"
+    real_home.mkdir()
+    link_home = tmp_path / "link_home"
+    link_home.symlink_to(real_home, target_is_directory=True)
+    monkeypatch.setattr(Path, "home", classmethod(lambda cls: link_home))
+
+    session = "legit"
+    events = _sample_events("legit")
+    log_path = real_home / ".claude" / "projects" / "-home-uc" / f"{session}.jsonl"
+    _write_jsonl(log_path, events)
+
+    resolved = agent_log_module._resolve_claude_path(session, "/home/uc")
+    assert resolved is not None
+    assert resolved.resolve() == log_path.resolve()

{pocketshell-0.4.0 → pocketshell-0.4.1}/tests/test_agents.py

@@ -25,6 +25,22 @@ from pocketshell import agents
 from pocketshell.cli import main
 
 
+@pytest.fixture(autouse=True)
+def _agent_binary_on_path(monkeypatch):
+    """Pretend the agent CLI is on PATH for every test by default.
+
+    ``launch_agent`` now preflights ``shutil.which(argv[0])`` (#774 §3) and
+    exits 127 when the binary is missing. The exec-shape tests inject a fake
+    ``execvpe`` precisely to assume the binary exists, so without this the
+    suite would become host-PATH dependent (e.g. ``opencode`` not installed
+    on CI). The dedicated missing-binary test overrides this with
+    ``which -> None``.
+    """
+    monkeypatch.setattr(
+        agents.shutil, "which", lambda name, *a, **k: f"/usr/bin/{name}"
+    )
+
+
 @pytest.fixture(autouse=True)
 def _restore_cwd():
     """Restore the working directory after each test.
@@ -437,6 +453,58 @@ def test_launch_agent_missing_dir_exits_two():
     assert exc.value.exit_code == 2
 
 
+# ---------------------------------------------------------------------------
+# Missing agent binary -> friendly 127 (issue #774 §3)
+#
+# Before the fix, a missing `claude`/`codex`/`opencode` let os.execvpe raise
+# a raw FileNotFoundError + Python traceback to the SSH client. The preflight
+# must instead emit the same friendly 127 + install hint every other
+# subcommand uses, and must NOT chdir or call execvpe.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("kind", agents.AGENT_KINDS)
+def test_launch_agent_missing_binary_exits_127(tmp_path, monkeypatch, kind):
+    monkeypatch.setattr(agents.shutil, "which", lambda *a, **k: None)
+    called = {"execvpe": False}
+
+    def fake_execvpe(*args, **kwargs):  # pragma: no cover - must not run
+        called["execvpe"] = True
+
+    cwd_before = os.getcwd()
+    with pytest.raises(click.exceptions.Exit) as exc:
+        agents.launch_agent(
+            _FakeCtx(),
+            kind,
+            str(tmp_path),
+            skip_permissions=True,
+            config_dir=None,
+            execvpe=fake_execvpe,
+        )
+    assert exc.value.exit_code == 127
+    # Preflight fired before the side effects: no chdir into the folder, and
+    # the exec was never attempted (so no raw FileNotFoundError traceback).
+    assert called["execvpe"] is False
+    assert os.getcwd() == cwd_before
+
+
+def test_cli_agent_missing_binary_exits_127(tmp_path, monkeypatch, capsys):
+    """End-to-end: the CLI returns 127 + a friendly stderr hint, not a
+    traceback, when the agent binary is absent.
+    """
+    monkeypatch.setattr(agents.shutil, "which", lambda *a, **k: None)
+
+    def fake_execvpe(*args, **kwargs):  # pragma: no cover - must not run
+        raise AssertionError("execvpe should not be reached on missing binary")
+
+    monkeypatch.setattr(agents.os, "execvpe", fake_execvpe)
+    rc = main(["agent", "opencode", "--dir", str(tmp_path)])
+    assert rc == 127
+    stderr = capsys.readouterr().err
+    assert "opencode" in stderr
+    assert "not installed" in stderr
+
+
 # ---------------------------------------------------------------------------
 # CLI wiring end-to-end (exec stubbed out)
 # ---------------------------------------------------------------------------

{pocketshell-0.4.0 → pocketshell-0.4.1}/tests/test_daemon.py

@@ -779,6 +779,48 @@ def test_jobs_mutation_invalidates_jobs_list_cache(tmp_path: Path) -> None:
     assert calls["list"] == 2
 
 
+def test_handler_exception_returns_generic_message_and_logs_detail(
+    tmp_path: Path,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """An unhandled handler exception must NOT leak its raw text — which
+    can embed internal host filesystem paths — over the socket. The
+    client gets a generic, detail-free message; the full traceback is
+    logged to the daemon's OWN stderr for operator debugging.
+    """
+    secret_path = "/home/operator/.config/pocketshell/secret-token.json"
+
+    def exploding_handler(_params: dict) -> dict:
+        # A realistic failure whose text embeds an internal host path.
+        raise FileNotFoundError(f"[Errno 2] No such file or directory: {secret_path!r}")
+
+    daemon = daemon_mod.Daemon(
+        socket_path=tmp_path / "daemon.sock",
+        methods={"boom.now": exploding_handler},
+    )
+
+    response = _dispatch_in_memory(daemon, "boom.now", {})
+
+    # The wire response carries only a generic message + the method name.
+    assert "error" in response
+    error = response["error"]
+    assert error["code"] == daemon_mod.JSONRPC_INTERNAL_ERROR
+    message = error["message"]
+    assert "boom.now" in message
+    # The internal path, the exception text, and even the exception type
+    # name must NOT be present in the client-facing message.
+    assert secret_path not in message
+    assert "No such file" not in message
+    assert "FileNotFoundError" not in message
+    assert "Errno" not in message
+
+    # The full detail (incl. the host path) IS available to the operator
+    # on the daemon's own stderr for debugging.
+    captured = capsys.readouterr()
+    assert "FileNotFoundError" in captured.err
+    assert secret_path in captured.err
+
+
 def test_daemon_registry_includes_sessions_and_jobs_methods() -> None:
     assert "sessions.list" in daemon_mod.DEFAULT_METHODS
     assert "jobs.list" in daemon_mod.DEFAULT_METHODS

{pocketshell-0.4.0 → pocketshell-0.4.1}/tests/test_jobs.py

@@ -20,8 +20,10 @@ The second-PR scope exercises:
 - `pocketshell jobs daemon start` forwards to `tmuxctl jobs daemon`
   with optional `--poll-interval` / `--run-once`.
 - `pocketshell jobs daemon status` returns 0/3 based on `pgrep`.
-- `pocketshell jobs daemon stop` returns 0 for "no match" (idempotent)
-  and 0 for "signalled at least one".
+- `pocketshell jobs daemon stop` resolves the daemon PID(s) via
+  `pgrep -f` + argv re-validation, then SIGTERMs exactly those PIDs via
+  `os.kill` (never a blunt `pkill -f`). Returns 0 for "no match"
+  (idempotent) and 0 for "signalled at least one".
 - Missing `tmuxctl` produces a friendly stderr message + exit 127.
 - stdout/stderr/exit-code from the subprocess are proxied verbatim.
 
@@ -33,6 +35,8 @@ tmuxctl exists on the host", not "the scheduler works".
 
 from __future__ import annotations
 
+import os
+import signal
 import subprocess
 from typing import Sequence
 from unittest.mock import patch
@@ -702,42 +706,129 @@ def test_jobs_daemon_status_without_pgrep_returns_not_running() -> None:
 # ----- daemon stop ---------------------------------------------------
 
 
-def test_jobs_daemon_stop_signals_running_process() -> None:
+def test_jobs_daemon_stop_signals_resolved_pids_only() -> None:
+    """`stop` SIGTERMs exactly the resolved daemon PIDs via `os.kill`.
+
+    It must NOT shell out to a blunt `pkill -TERM -f` (the old broad
+    behaviour that signalled every matching command line on the host).
+    """
     runner = CliRunner()
-    with patch("pocketshell.jobs.shutil.which", return_value="/fake/pkill"), patch(
-        "pocketshell.jobs.subprocess.run",
-        return_value=_fake_completed(stdout="", returncode=0),
+    killed: list[tuple[int, int]] = []
+    with patch("pocketshell.jobs.shutil.which", return_value="/fake/pgrep"), patch(
+        "pocketshell.jobs._resolve_daemon_pids", return_value=[4321]
+    ), patch(
+        "pocketshell.jobs.os.kill",
+        side_effect=lambda pid, sig: killed.append((pid, sig)),
+    ), patch(
+        "pocketshell.jobs.subprocess.run"
     ) as run:
         result = runner.invoke(jobs_group, ["daemon", "stop"])
     assert result.exit_code == 0, result.output
     assert "stopped" in result.output.lower()
-    invoked: Sequence[str] = run.call_args.args[0]
-    # Same anchored pattern as `status`.
-    assert invoked[0:3] == ["/fake/pkill", "-TERM", "-f"]
-    assert "tmuxctl jobs daemon" in invoked[3]
+    # Exactly the resolved PID, with SIGTERM — no pkill, no broad match.
+    assert killed == [(4321, signal.SIGTERM)]
+    # No `pkill -TERM -f <pattern>` subprocess was ever launched.
+    for call in run.call_args_list:
+        argv = call.args[0]
+        assert "pkill" not in (argv[0] if argv else "")
 
 
 def test_jobs_daemon_stop_is_idempotent_when_not_running() -> None:
     runner = CliRunner()
-    with patch("pocketshell.jobs.shutil.which", return_value="/fake/pkill"), patch(
-        "pocketshell.jobs.subprocess.run",
-        # pkill exits 1 when no process matches; treat as no-op success.
-        return_value=_fake_completed(stdout="", returncode=1),
-    ):
+    with patch("pocketshell.jobs.shutil.which", return_value="/fake/pgrep"), patch(
+        "pocketshell.jobs._resolve_daemon_pids", return_value=[]
+    ), patch("pocketshell.jobs.os.kill") as kill:
+        result = runner.invoke(jobs_group, ["daemon", "stop"])
+    assert result.exit_code == 0, result.output
+    assert "not running" in result.output.lower()
+    kill.assert_not_called()
+
+
+def test_jobs_daemon_stop_treats_raced_exit_as_not_running() -> None:
+    """A PID that vanished between resolve and kill is not an error."""
+    runner = CliRunner()
+    with patch("pocketshell.jobs.shutil.which", return_value="/fake/pgrep"), patch(
+        "pocketshell.jobs._resolve_daemon_pids", return_value=[999]
+    ), patch("pocketshell.jobs.os.kill", side_effect=ProcessLookupError):
         result = runner.invoke(jobs_group, ["daemon", "stop"])
     assert result.exit_code == 0, result.output
     assert "not running" in result.output.lower()
 
 
-def test_jobs_daemon_stop_without_pkill_returns_127() -> None:
+def test_jobs_daemon_stop_without_pgrep_returns_127() -> None:
     runner = CliRunner()
     with patch("pocketshell.jobs.shutil.which", return_value=None), patch(
-        "pocketshell.jobs.subprocess.run"
-    ) as run:
+        "pocketshell.jobs.os.kill"
+    ) as kill:
         result = runner.invoke(jobs_group, ["daemon", "stop"])
     assert result.exit_code == 127
-    assert "pkill" in result.output.lower()
-    run.assert_not_called()
+    assert "pgrep" in result.output.lower()
+    kill.assert_not_called()
+
+
+# ----- daemon stop: PID resolution + argv validation (narrowing) -----
+
+
+def test_argv_is_daemon_accepts_real_invocations() -> None:
+    from pocketshell.jobs import _argv_is_daemon
+
+    assert _argv_is_daemon(["/home/u/.local/bin/tmuxctl", "jobs", "daemon"])
+    assert _argv_is_daemon(["tmuxctl", "jobs", "daemon", "--poll-interval", "5"])
+    # A `python …/tmuxctl jobs daemon` shim still matches on the tmuxctl token.
+    assert _argv_is_daemon(["python3", "/usr/bin/tmuxctl", "jobs", "daemon"])
+
+
+def test_argv_is_daemon_rejects_coincidental_command_lines() -> None:
+    """The whole point of the narrowing: a command line that merely
+    *contains* the substring `tmuxctl jobs daemon` (e.g. an editor
+    opening a file with that name) must NOT be classed as the daemon,
+    even though `pgrep -f`/`pkill -f` would regex-match it.
+    """
+    from pocketshell.jobs import _argv_is_daemon
+
+    # Editor opening a note whose filename contains the phrase.
+    assert not _argv_is_daemon(["vim", "notes/tmuxctl jobs daemon.md"])
+    # Another shell literally typing the command as one argv element.
+    assert not _argv_is_daemon(["bash", "-c", "tmuxctl jobs daemon"])
+    # A different tmuxctl subcommand.
+    assert not _argv_is_daemon(["tmuxctl", "jobs", "list"])
+    # `tmuxctl jobs daemon-something-else` style verb.
+    assert not _argv_is_daemon(["tmuxctl", "jobs", "daemon-foo"])
+    assert not _argv_is_daemon([])
+    assert not _argv_is_daemon(["tmuxctl"])
+
+
+def test_resolve_daemon_pids_drops_coincidental_match_and_self() -> None:
+    """`_resolve_daemon_pids` re-validates each `pgrep` candidate's real
+    argv and excludes our own PID, so a coincidental command-line match
+    (which `pgrep -f`/`pkill -f` would have signalled) is dropped.
+    """
+    own = os.getpid()
+
+    def fake_argv(pid: int):
+        return {
+            111: ["/usr/bin/tmuxctl", "jobs", "daemon"],  # genuine daemon
+            222: ["vim", "tmuxctl jobs daemon.md"],  # coincidental match
+            own: ["python3", "/x/tmuxctl", "jobs", "daemon"],  # ourselves
+        }.get(pid)
+
+    with patch("pocketshell.jobs.shutil.which", return_value="/fake/pgrep"), patch(
+        "pocketshell.jobs.subprocess.run",
+        return_value=_fake_completed(stdout=f"111\n222\n{own}\n", returncode=0),
+    ), patch("pocketshell.jobs._read_proc_argv", side_effect=fake_argv):
+        from pocketshell.jobs import _resolve_daemon_pids
+
+        pids = _resolve_daemon_pids()
+    # Only the genuine daemon PID survives: coincidental 222 and our own
+    # PID are both excluded.
+    assert pids == [111]
+
+
+def test_resolve_daemon_pids_empty_without_pgrep() -> None:
+    with patch("pocketshell.jobs.shutil.which", return_value=None):
+        from pocketshell.jobs import _resolve_daemon_pids
+
+        assert _resolve_daemon_pids() == []
 
 
 # ----- missing-binary handling ---------------------------------------

{pocketshell-0.4.0 → pocketshell-0.4.1}/tests/test_qr_share.py

@@ -26,11 +26,13 @@ import pathlib
 from typing import List
 from unittest.mock import patch
 
+import click
+import pytest
 from click.testing import CliRunner
 
 from pocketshell import qr_share
 from pocketshell.cli import cli
-from pocketshell.qr_share import qr_share_command
+from pocketshell.qr_share import _read_private_key, build_payload, qr_share_command
 
 
 # ---------------------------------------------------------------------------
@@ -80,6 +82,90 @@ def test_envelope_prefix() -> None:
     assert single.startswith("pocketshell.qr.v1?")
 
 
+# ---------------------------------------------------------------------------
+# Private-key reading — friendly errors over raw stack traces (#774 §6, #777 G2).
+#
+# `_read_private_key` is the single point where `qr-share` turns the resolved
+# IdentityFile path into the PEM that lands in the payload's `privateKeyPem`.
+# A bad path must surface as a Click-formatted error (exit 1 with a clear
+# message), never an unhandled `FileNotFoundError` traceback.
+# ---------------------------------------------------------------------------
+
+
+def test_read_private_key_missing_file_raises_friendly_click_error(
+    tmp_path: pathlib.Path,
+) -> None:
+    """A non-existent key path raises a friendly `ClickException` naming the
+    path — not a raw `FileNotFoundError` / stack trace."""
+    missing = tmp_path / "id_does_not_exist"
+    assert not missing.exists()
+    with pytest.raises(click.ClickException) as exc_info:
+        _read_private_key(missing)
+    # The message is user-facing and points at the offending path so the user
+    # can fix the `--key` / IdentityFile they passed.
+    message = exc_info.value.message
+    assert "key file not found" in message
+    assert str(missing) in message
+
+
+def test_read_private_key_reads_and_strips_an_existing_key(
+    tmp_path: pathlib.Path,
+) -> None:
+    """An existing key file is read and surrounding whitespace stripped (the
+    PEM lands without a trailing newline in the payload)."""
+    key_path = tmp_path / "id_ed25519"
+    key_path.write_text(
+        "\n-----BEGIN OPENSSH PRIVATE KEY-----\nabc\n-----END OPENSSH PRIVATE KEY-----\n\n"
+    )
+    pem = _read_private_key(key_path)
+    assert pem.startswith("-----BEGIN OPENSSH PRIVATE KEY-----")
+    assert pem.endswith("-----END OPENSSH PRIVATE KEY-----")
+    # `.strip()` removed the leading/trailing blank lines.
+    assert not pem.startswith("\n")
+    assert not pem.endswith("\n")
+
+
+def test_read_private_key_empty_file_raises_friendly_click_error(
+    tmp_path: pathlib.Path,
+) -> None:
+    """An existing-but-empty (or whitespace-only) key file is rejected with a
+    friendly `ClickException` naming the path — never a silent "" PEM that would
+    land an empty `privateKeyPem` in the payload.
+
+    This was previously a characterization of the un-guarded behaviour (returned
+    "" without raising). The #777 review recommended a small production guard;
+    `_read_private_key` now raises for an empty file, mirroring the
+    missing-file case.
+    """
+    empty = tmp_path / "id_empty"
+    empty.write_text("   \n\t\n")
+    with pytest.raises(click.ClickException) as exc_info:
+        _read_private_key(empty)
+    message = exc_info.value.message
+    assert "private key file is empty" in message
+    assert str(empty) in message
+
+
+def test_build_payload_missing_explicit_key_file_surfaces_friendly_error(
+    tmp_path: pathlib.Path,
+) -> None:
+    """End-to-end: `build_payload(--host ... --key <missing>)` propagates the
+    friendly `_read_private_key` error rather than crashing — the path the CLI
+    actually takes when a user points `--key` at a bad file."""
+    missing = tmp_path / "nope_id"
+    with pytest.raises(click.ClickException) as exc_info:
+        build_payload(
+            alias=None,
+            host="prod.example.com",
+            user="ubuntu",
+            port=22,
+            key=str(missing),
+            name="prod",
+            key_name=None,
+        )
+    assert "key file not found" in exc_info.value.message
+
+
 # ---------------------------------------------------------------------------
 # CLI-surface tests.
 # ---------------------------------------------------------------------------