pocketshell 0.4.6__tar.gz → 0.4.8__tar.gz

{pocketshell-0.4.6 → pocketshell-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.4.6
+Version: 0.4.8
 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.6 → pocketshell-0.4.8}/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.6"
+version = "0.4.8"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

pocketshell-0.4.8/src/pocketshell/cgroup_agents.py

@@ -0,0 +1,309 @@
+"""Scope/cgroup-based agent-kind detection for the ``agents.kind_for_panes`` RPC.
+
+Replaces the fragile client-side ``ps -eo … | grep`` agent scan (issue #809 /
+#811) with a deterministic server-side read of cgroup v2 + ``/proc``:
+
+1. **pane → scope** — read ``/proc/<pane_pid>/cgroup``. On a cgroup-v2 host the
+   sole ``0::`` line carries the cgroup-relative path of the leaf, which for a
+   PocketShell session is ``…/robust.slice/tmuxctl-<session>.scope`` (the
+   deterministic name `tmuxctl` assigns at ``robust.scope_unit_name``). Sessions
+   started outside tmuxctl resolve to ``tmux-spawn-<uuid>.scope`` or a login
+   scope; "no scope" is detectable, never a crash.
+2. **scope → procs** — read that cgroup's ``cgroup.procs`` then each
+   ``/proc/<pid>/comm`` + ``/proc/<pid>/cmdline``. No ``systemctl status``
+   shell-out (it forks, pretty-prints ~100 ms, and truncates the proc list);
+   raw cgroupfs reads are ~7-17 ms and complete.
+3. **classify** — match comm/cmdline tokens for claude / codex / opencode,
+   mirroring the proven token rules in
+   ``shared/core-agents/.../AgentDetector.kt`` (``namesAgent`` /
+   ``containsCommandToken``): a word-boundary match so ``codex`` matches a bare
+   ``codex`` comm AND a ``node …/codex`` node-wrapped cmdline, but
+   ``codex-helper`` substrings of an unrelated path do not false-positive on the
+   raw token alone.
+
+All filesystem roots are injectable (``proc_root`` / ``cgroup_mount``) so the
+classifier unit-tests against a synthetic ``/proc``-like tree with zero live
+sessions. Every read is defensive: a missing pid, a pid that vanished between
+the ``cgroup.procs`` read and the ``comm`` read, a no-scope pane, or a
+permission error degrades to ``agent_kind = "none"`` (or an explicit
+``"unknown"`` for an unreadable pane) — never an exception that fails the whole
+batch.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Iterable, Mapping, Optional, Sequence
+
+# Default cgroup v2 mount point on Linux. Injectable for tests.
+DEFAULT_CGROUP_MOUNT = "/sys/fs/cgroup"
+DEFAULT_PROC_ROOT = "/proc"
+
+# Agent kinds returned to the client. ``none`` = pane resolved to a scope (or a
+# readable proc set) but no agent process is present. ``unknown`` = the pane's
+# pid / cgroup could not be read at all (vanished, permission), so we cannot
+# even assert "no agent" — the client should treat it as not-yet-known, not as
+# a confirmed plain shell.
+AGENT_CLAUDE = "claude"
+AGENT_CODEX = "codex"
+AGENT_OPENCODE = "opencode"
+AGENT_NONE = "none"
+AGENT_UNKNOWN = "unknown"
+
+# Token patterns mirror AgentDetector.namesAgent (Kotlin). Each is wrapped in
+# the same word-boundary guard as Kotlin's `containsCommandToken` so the token
+# only matches as a whole command word — bounded by start/end, whitespace, or
+# the shell/path delimiters `/ | ; & ( ) ' " \``. This lets `codex` match both
+# a bare `codex` comm and a `node /…/codex` node-wrapped cmdline while a stray
+# substring inside an unrelated token does not light up.
+_AGENT_TOKEN_PATTERNS: Sequence[tuple[str, str]] = (
+    # (agent_kind, command-token regex — verbatim from the Kotlin rules)
+    (AGENT_CLAUDE, r"claude(?:-?code)?"),
+    (AGENT_CODEX, r"codex"),
+    (AGENT_OPENCODE, r"open[-_]?code(?:[-_][a-z0-9]+)?"),
+)
+
+# Pre-compile the boundary-wrapped matchers once. The guard is identical to
+# `containsCommandToken`: a leading start/delimiter and a trailing
+# end/delimiter lookahead, case-insensitive.
+_BOUNDARY_LEAD = r"(^|[\s/|;&('\"`])"
+_BOUNDARY_TAIL = r"(?=$|[\s/|;&):'\"`])"
+_COMPILED_TOKENS: Sequence[tuple[str, "re.Pattern[str]"]] = tuple(
+    (kind, re.compile(_BOUNDARY_LEAD + pattern + _BOUNDARY_TAIL))
+    for kind, pattern in _AGENT_TOKEN_PATTERNS
+)
+
+# Extract the scope unit basename from a cgroup-v2 relative path. Matches both
+# the tmuxctl session scope and the non-tmuxctl spawn scope so "which scope"
+# is reported even when no agent is detected.
+_SCOPE_BASENAME_RE = re.compile(r"(?P<scope>(?:tmuxctl|tmux-spawn)-[^/]+\.scope)")
+
+
+@dataclass(frozen=True)
+class PaneAgentResult:
+    """One pane's classification result.
+
+    ``scope`` is the cgroup scope basename the pane resolved to (e.g.
+    ``tmuxctl-git-pocketshell.scope``) or ``None`` if the pane had no
+    tmuxctl/spawn scope (login shell, no systemd scopes). ``evidence_pid`` is
+    the pid of the process whose comm/cmdline named the agent, for debugging.
+    """
+
+    pane_id: Optional[str]
+    agent_kind: str
+    scope: Optional[str]
+    evidence_pid: Optional[int] = None
+
+    def to_json(self) -> dict[str, object]:
+        out: dict[str, object] = {
+            "pane_id": self.pane_id,
+            "agent_kind": self.agent_kind,
+            "scope": self.scope,
+        }
+        if self.evidence_pid is not None:
+            out["evidence_pid"] = self.evidence_pid
+        return out
+
+
+def classify_token(text: str) -> Optional[str]:
+    """Return the agent kind named by ``text`` (a comm or cmdline), or ``None``.
+
+    Mirrors ``AgentDetector.namesAgent``: lowercases then applies the
+    word-boundary command-token match for each engine, in claude→codex→opencode
+    order. The order only matters in the impossible case of a single string
+    naming two engines; a real comm/cmdline names at most one.
+    """
+    lowered = text.lower()
+    for kind, pattern in _COMPILED_TOKENS:
+        if pattern.search(lowered):
+            return kind
+    return None
+
+
+def _read_text(path: Path) -> Optional[str]:
+    """Read a small ``/proc``/cgroupfs file, returning ``None`` on any error.
+
+    cgroupfs and ``/proc`` files can race away between enumeration and read
+    (the pid exits), or be unreadable; callers treat ``None`` as "skip", never
+    as a fatal error.
+    """
+    try:
+        return path.read_text(encoding="utf-8", errors="replace")
+    except (FileNotFoundError, ProcessLookupError, PermissionError, OSError):
+        return None
+
+
+def _read_cmdline(path: Path) -> Optional[str]:
+    """Read a ``/proc/<pid>/cmdline`` (NUL-delimited) as a space-joined string."""
+    try:
+        raw = path.read_bytes()
+    except (FileNotFoundError, ProcessLookupError, PermissionError, OSError):
+        return None
+    if not raw:
+        return ""
+    # cmdline args are NUL-separated, trailing NUL terminates the last arg.
+    decoded = raw.decode("utf-8", errors="replace")
+    return " ".join(part for part in decoded.split("\x00") if part).strip()
+
+
+def scope_relpath_for_pid(
+    pane_pid: int,
+    *,
+    proc_root: str = DEFAULT_PROC_ROOT,
+) -> Optional[str]:
+    """Resolve a pid's cgroup-v2 relative scope path from ``/proc/<pid>/cgroup``.
+
+    Returns the cgroup-relative path of the leaf cgroup (the part after the
+    ``0::``), e.g.
+    ``/user.slice/…/robust.slice/tmuxctl-git-pocketshell.scope``. Returns
+    ``None`` when the pid is gone, unreadable, or the cgroup file is not
+    cgroup-v2 unified (no ``0::`` line).
+    """
+    content = _read_text(Path(proc_root) / str(pane_pid) / "cgroup")
+    if content is None:
+        return None
+    for line in content.splitlines():
+        # cgroup v2 unified hierarchy: exactly one line "0::<path>".
+        if line.startswith("0::"):
+            relpath = line[len("0::"):].strip()
+            return relpath or None
+    return None
+
+
+def scope_basename(relpath: str) -> Optional[str]:
+    """Return the ``tmuxctl-*.scope`` / ``tmux-spawn-*.scope`` basename, if any."""
+    match = _SCOPE_BASENAME_RE.search(relpath)
+    if match:
+        return match.group("scope")
+    return None
+
+
+def _scope_procs(
+    relpath: str,
+    *,
+    cgroup_mount: str = DEFAULT_CGROUP_MOUNT,
+) -> Optional[list[int]]:
+    """Read ``cgroup.procs`` for the cgroup at ``relpath``.
+
+    ``relpath`` is the cgroup-v2 relative path from
+    :func:`scope_relpath_for_pid`; the absolute cgroupfs path is the mount plus
+    that relative path. Returns the list of pids, or ``None`` if the cgroup is
+    gone / unreadable (e.g. the session ended between the pane read and now).
+    """
+    # relpath is absolute-style ("/user.slice/…"); join under the mount.
+    cgroup_dir = Path(cgroup_mount) / relpath.lstrip("/")
+    content = _read_text(cgroup_dir / "cgroup.procs")
+    if content is None:
+        return None
+    pids: list[int] = []
+    for token in content.split():
+        try:
+            pids.append(int(token))
+        except ValueError:
+            continue
+    return pids
+
+
+def classify_scope_procs(
+    pids: Iterable[int],
+    *,
+    proc_root: str = DEFAULT_PROC_ROOT,
+) -> tuple[str, Optional[int]]:
+    """Classify the agent kind present among ``pids`` by their comm + cmdline.
+
+    Returns ``(agent_kind, evidence_pid)``. Reads each pid's ``comm`` first
+    (cheap, definitive for a non-wrapped CLI like ``claude``/``codex``) then
+    its ``cmdline`` (catches the node-wrapped form where ``comm`` is
+    ``node``/``MainThread`` but the cmdline carries ``node /…/codex``). The
+    first pid that names an agent wins; if none do, returns ``("none", None)``.
+    """
+    proc = Path(proc_root)
+    for pid in pids:
+        comm = _read_text(proc / str(pid) / "comm")
+        if comm is not None:
+            kind = classify_token(comm.strip())
+            if kind is not None:
+                return kind, pid
+        cmdline = _read_cmdline(proc / str(pid) / "cmdline")
+        if cmdline:
+            kind = classify_token(cmdline)
+            if kind is not None:
+                return kind, pid
+    return AGENT_NONE, None
+
+
+def kind_for_pane(
+    pane_pid: int,
+    *,
+    pane_id: Optional[str] = None,
+    proc_root: str = DEFAULT_PROC_ROOT,
+    cgroup_mount: str = DEFAULT_CGROUP_MOUNT,
+) -> PaneAgentResult:
+    """Resolve one pane's agent kind end-to-end (pane_pid → scope → classify).
+
+    Never raises: an unreadable pane pid yields ``agent_kind="unknown"`` (we
+    cannot even assert "no agent"); a readable scope with no agent process
+    yields ``agent_kind="none"``.
+    """
+    relpath = scope_relpath_for_pid(pane_pid, proc_root=proc_root)
+    if relpath is None:
+        # pid gone / cgroup unreadable — we cannot say anything definitive.
+        return PaneAgentResult(
+            pane_id=pane_id, agent_kind=AGENT_UNKNOWN, scope=None
+        )
+
+    scope = scope_basename(relpath)
+    pids = _scope_procs(relpath, cgroup_mount=cgroup_mount)
+    if pids is None:
+        # The cgroup itself is gone/unreadable even though the pane's cgroup
+        # line resolved — treat as unknown (the session likely just ended).
+        return PaneAgentResult(
+            pane_id=pane_id, agent_kind=AGENT_UNKNOWN, scope=scope
+        )
+
+    agent_kind, evidence_pid = classify_scope_procs(pids, proc_root=proc_root)
+    return PaneAgentResult(
+        pane_id=pane_id,
+        agent_kind=agent_kind,
+        scope=scope,
+        evidence_pid=evidence_pid,
+    )
+
+
+def kind_for_panes(
+    panes: Iterable[Mapping[str, object]],
+    *,
+    proc_root: str = DEFAULT_PROC_ROOT,
+    cgroup_mount: str = DEFAULT_CGROUP_MOUNT,
+) -> list[dict[str, object]]:
+    """Batch classifier: resolve agent kind for every pane in ``panes``.
+
+    Each pane is a mapping with ``pane_pid`` (int, required) and an optional
+    ``pane_id`` (passed through so the client can correlate). A pane with a
+    missing/invalid ``pane_pid`` yields ``agent_kind="unknown"`` rather than
+    failing the batch — one bad pane never sinks the others.
+    """
+    results: list[dict[str, object]] = []
+    for pane in panes:
+        pane_id = pane.get("pane_id")
+        pane_id_str = str(pane_id) if pane_id is not None else None
+        raw_pid = pane.get("pane_pid")
+        try:
+            pane_pid = int(raw_pid)  # type: ignore[arg-type]
+        except (TypeError, ValueError):
+            results.append(
+                PaneAgentResult(
+                    pane_id=pane_id_str, agent_kind=AGENT_UNKNOWN, scope=None
+                ).to_json()
+            )
+            continue
+        result = kind_for_pane(
+            pane_pid,
+            pane_id=pane_id_str,
+            proc_root=proc_root,
+            cgroup_mount=cgroup_mount,
+        )
+        results.append(result.to_json())
+    return results

{pocketshell-0.4.6 → pocketshell-0.4.8}/src/pocketshell/daemon.py

@@ -527,6 +527,53 @@ def _jobs_status_handler(params: Mapping[str, Any]) -> dict[str, Any]:
     return _jobs.daemon_handler_status(dict(params))
 
 
+# ---------------------------------------------------------------------------
+# Method: agents.kind_for_panes
+# ---------------------------------------------------------------------------
+
+
+def _agents_kind_for_panes_handler(params: Mapping[str, Any]) -> dict[str, Any]:
+    """Classify the agent kind running in each pane's cgroup scope.
+
+    Replaces the client's fragile ``ps -eo … | grep`` agent scan (#809/#811)
+    with a server-side cgroup-v2 + ``/proc`` read: each pane's ``pane_pid``
+    resolves to its ``tmuxctl-<session>.scope`` via ``/proc/<pid>/cgroup``, the
+    scope's ``cgroup.procs`` are read, and each proc's ``comm``/``cmdline`` is
+    matched against the claude/codex/opencode token rules (mirrored from
+    ``AgentDetector.namesAgent``). No ``systemctl`` shell-out — raw cgroupfs.
+
+    Request params::
+
+        {"panes": [{"pane_id": "%1", "pane_pid": 2647034}, ...]}
+
+    Result::
+
+        {"results": [
+            {"pane_id": "%1", "agent_kind": "claude",
+             "scope": "tmuxctl-git-pocketshell.scope", "evidence_pid": 2647069},
+            ...
+        ]}
+
+    ``agent_kind`` is one of ``claude`` / ``codex`` / ``opencode`` / ``none``
+    (readable scope, no agent) / ``unknown`` (pane pid/cgroup unreadable). One
+    bad pane never sinks the batch.
+    """
+    from pocketshell import cgroup_agents as _cgroup_agents
+
+    raw_panes = params.get("panes")
+    if raw_panes is None:
+        panes: list[Mapping[str, Any]] = []
+    elif isinstance(raw_panes, list):
+        panes = [p for p in raw_panes if isinstance(p, Mapping)]
+    else:
+        raise _RpcError(
+            JSONRPC_INVALID_PARAMS,
+            "agents.kind_for_panes: `panes` must be a list of objects",
+        )
+
+    return {"results": _cgroup_agents.kind_for_panes(panes)}
+
+
 # Single shared registry; tests can register additional methods via
 # :meth:`Daemon.register_method` on a fresh instance without touching
 # this dict.
@@ -544,6 +591,7 @@ DEFAULT_METHODS: Mapping[str, RpcHandler] = {
     "jobs.edit": _jobs_edit_handler,
     "jobs.remove": _jobs_remove_handler,
     "jobs.status": _jobs_status_handler,
+    "agents.kind_for_panes": _agents_kind_for_panes_handler,
 }
 
 

pocketshell-0.4.8/tests/test_cgroup_agents.py

@@ -0,0 +1,365 @@
+"""Tests for cgroup/scope-based agent classification (issue #809 / #811).
+
+The classifier reads a cgroup-v2 ``/sys/fs/cgroup`` tree plus ``/proc`` to map
+each pane's ``pane_pid`` to its ``tmuxctl-<session>.scope`` and classify the
+agent process running inside. These tests build a **synthetic** ``/proc``-like
+and cgroupfs-like tree on ``tmp_path`` and point the classifier at it via the
+injectable ``proc_root`` / ``cgroup_mount`` roots, so nothing depends on a live
+tmux/agent session — they reproduce the real on-box layout proven in the #811
+design spike (claude as ``comm=claude``; codex node-wrapped as
+``comm=MainThread`` + ``cmdline=node …/codex``; etc.).
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Optional
+
+import pytest
+
+from pocketshell import cgroup_agents
+from pocketshell.cgroup_agents import (
+    AGENT_CLAUDE,
+    AGENT_CODEX,
+    AGENT_NONE,
+    AGENT_OPENCODE,
+    AGENT_UNKNOWN,
+    classify_token,
+)
+
+
+# ---------------------------------------------------------------------------
+# Synthetic-filesystem fixture builder
+# ---------------------------------------------------------------------------
+
+
+class _FakeHost:
+    """Builds a synthetic ``/proc`` + cgroup-v2 tree under ``tmp_path``.
+
+    Mirrors the real on-box layout: a pane shell pid lives directly inside its
+    ``…/robust.slice/<scope>``; the scope's ``cgroup.procs`` lists every pid in
+    the scope; each pid has a ``/proc/<pid>/comm`` and ``/proc/<pid>/cmdline``.
+    """
+
+    # The relative cgroup path prefix every scope lives under, matching the
+    # real `/proc/<pid>/cgroup` `0::` line on this box.
+    ROBUST_PREFIX = (
+        "/user.slice/user-1000.slice/user@1000.service/robust.slice"
+    )
+
+    def __init__(self, root: Path) -> None:
+        self.proc_root = root / "proc"
+        self.cgroup_mount = root / "cgroup"
+        self.proc_root.mkdir(parents=True, exist_ok=True)
+        self.cgroup_mount.mkdir(parents=True, exist_ok=True)
+
+    def _scope_relpath(self, scope: str) -> str:
+        return f"{self.ROBUST_PREFIX}/{scope}"
+
+    def add_proc(
+        self,
+        pid: int,
+        *,
+        scope: Optional[str],
+        comm: str,
+        cmdline: str,
+    ) -> None:
+        """Create a synthetic ``/proc/<pid>`` whose cgroup line names ``scope``.
+
+        When ``scope`` is ``None`` the cgroup line points at a bare login path
+        with no tmuxctl/spawn scope (the non-tmuxctl session case).
+        """
+        proc_dir = self.proc_root / str(pid)
+        proc_dir.mkdir(parents=True, exist_ok=True)
+        (proc_dir / "comm").write_text(comm + "\n", encoding="utf-8")
+        # cmdline is NUL-separated with a trailing NUL on real /proc.
+        cmdline_bytes = b"\x00".join(
+            part.encode("utf-8") for part in cmdline.split(" ")
+        )
+        if cmdline_bytes:
+            cmdline_bytes += b"\x00"
+        (proc_dir / "cmdline").write_bytes(cmdline_bytes)
+
+        if scope is None:
+            relpath = f"{self.ROBUST_PREFIX}/../user-1000.slice/session-1.scope"
+        else:
+            relpath = self._scope_relpath(scope)
+        (proc_dir / "cgroup").write_text(f"0::{relpath}\n", encoding="utf-8")
+
+    def set_scope_procs(self, scope: str, pids: list[int]) -> None:
+        """Write ``cgroup.procs`` for a scope listing the given pids."""
+        scope_dir = (
+            self.cgroup_mount
+            / self.ROBUST_PREFIX.lstrip("/")
+            / scope
+        )
+        scope_dir.mkdir(parents=True, exist_ok=True)
+        body = "".join(f"{pid}\n" for pid in pids)
+        (scope_dir / "cgroup.procs").write_text(body, encoding="utf-8")
+
+
+@pytest.fixture()
+def host(tmp_path: Path) -> _FakeHost:
+    return _FakeHost(tmp_path)
+
+
+def _classify(host: _FakeHost, pane_pid: int, pane_id: str = "%1"):
+    return cgroup_agents.kind_for_pane(
+        pane_pid,
+        pane_id=pane_id,
+        proc_root=str(host.proc_root),
+        cgroup_mount=str(host.cgroup_mount),
+    )
+
+
+# ---------------------------------------------------------------------------
+# classify_token — the pure token-rule mirror of AgentDetector.namesAgent
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    ("text", "expected"),
+    [
+        ("claude", AGENT_CLAUDE),
+        ("claude --dangerously-skip-permissions", AGENT_CLAUDE),
+        ("claude-code", AGENT_CLAUDE),
+        ("codex", AGENT_CODEX),
+        ("/home/alexey/.nvm/versions/node/v24/bin/codex --foo", AGENT_CODEX),
+        ("node /home/alexey/.nvm/.../codex --bypass", AGENT_CODEX),
+        ("opencode", AGENT_OPENCODE),
+        ("open-code", AGENT_OPENCODE),
+        ("opencode-tui", AGENT_OPENCODE),
+        # Plain shells / unrelated processes name no agent.
+        ("bash", None),
+        ("/bin/bash -l", None),
+        ("node /some/other/app.js", None),
+        # `codex` as a whole command word (space-delimited) matches; the
+        # `codexicon` substring case is covered separately below.
+        ("git commit && codex", AGENT_CODEX),
+        ("", None),
+    ],
+)
+def test_classify_token(text: str, expected: Optional[str]) -> None:
+    assert classify_token(text) == expected
+
+
+def test_classify_token_substring_does_not_false_positive() -> None:
+    # `codexedit` is one token, not a `codex` command word — the boundary
+    # guard (mirroring containsCommandToken) must NOT match it.
+    assert classify_token("codexedit") is None
+    assert classify_token("myclaudeproxy") is None
+
+
+# ---------------------------------------------------------------------------
+# kind_for_pane — end-to-end pane_pid → scope → classify
+# ---------------------------------------------------------------------------
+
+
+def test_claude_scope(host: _FakeHost) -> None:
+    """A scope with a bare `comm=claude` shell child classifies as claude."""
+    scope = "tmuxctl-git-pocketshell.scope"
+    host.add_proc(2647034, scope=scope, comm="bash", cmdline="/bin/bash -l")
+    host.add_proc(
+        2647069,
+        scope=scope,
+        comm="claude",
+        cmdline="claude --dangerously-skip-permissions",
+    )
+    host.set_scope_procs(scope, [2647034, 2647069])
+
+    result = _classify(host, 2647034)
+    assert result.agent_kind == AGENT_CLAUDE
+    assert result.scope == scope
+    assert result.evidence_pid == 2647069
+
+
+def test_codex_node_wrapped_scope(host: _FakeHost) -> None:
+    """Node-wrapped codex: comm is `MainThread`, cmdline carries node …/codex.
+
+    This is the exact live layout proven in the #811 spike for
+    `tmuxctl-git-3d-models.scope`.
+    """
+    scope = "tmuxctl-git-3d-models.scope"
+    host.add_proc(756261, scope=scope, comm="bash", cmdline="/bin/bash -l")
+    host.add_proc(
+        756501,
+        scope=scope,
+        comm="MainThread",
+        cmdline=(
+            "node /home/alexey/.nvm/versions/node/v24.13.1/bin/codex "
+            "--dangerously-bypass-approvals-and-sandbox"
+        ),
+    )
+    host.add_proc(
+        756656,
+        scope=scope,
+        comm="codex",
+        cmdline="/home/alexey/.../@openai/codex/node_modules/...",
+    )
+    host.set_scope_procs(scope, [756261, 756501, 756656])
+
+    result = _classify(host, 756261)
+    assert result.agent_kind == AGENT_CODEX
+    assert result.scope == scope
+    # The node-wrapper MainThread pid is enumerated before the bare codex pid,
+    # so its cmdline is the evidence.
+    assert result.evidence_pid == 756501
+
+
+def test_opencode_scope(host: _FakeHost) -> None:
+    scope = "tmuxctl-git-faq-assistant.scope"
+    host.add_proc(900001, scope=scope, comm="bash", cmdline="/bin/bash -l")
+    host.add_proc(
+        900002, scope=scope, comm="opencode", cmdline="opencode --foo"
+    )
+    host.set_scope_procs(scope, [900001, 900002])
+
+    result = _classify(host, 900001)
+    assert result.agent_kind == AGENT_OPENCODE
+    assert result.scope == scope
+    assert result.evidence_pid == 900002
+
+
+def test_plain_shell_scope_is_none(host: _FakeHost) -> None:
+    """A scope with only a plain shell (no agent) classifies as `none`."""
+    scope = "tmuxctl-git-datamailer.scope"
+    host.add_proc(800001, scope=scope, comm="bash", cmdline="/bin/bash -l")
+    host.add_proc(800002, scope=scope, comm="vim", cmdline="vim notes.txt")
+    host.set_scope_procs(scope, [800001, 800002])
+
+    result = _classify(host, 800001)
+    assert result.agent_kind == AGENT_NONE
+    assert result.scope == scope
+    assert result.evidence_pid is None
+
+
+def test_missing_pid_is_unknown(host: _FakeHost) -> None:
+    """A pane_pid with no /proc entry (vanished) is `unknown`, not a crash."""
+    result = _classify(host, 4242424)
+    assert result.agent_kind == AGENT_UNKNOWN
+    assert result.scope is None
+    assert result.evidence_pid is None
+
+
+def test_no_tmuxctl_scope_is_none_with_null_scope(host: _FakeHost) -> None:
+    """A non-tmuxctl pane (login scope) reports scope=None.
+
+    The pid resolves (cgroup readable) but there is no tmuxctl/spawn scope, so
+    we cannot read a scope's cgroup.procs — degrade to `unknown` rather than
+    pretending we proved "no agent".
+    """
+    host.add_proc(700001, scope=None, comm="bash", cmdline="/bin/bash -l")
+    result = _classify(host, 700001)
+    # No scope basename, and the login-scope cgroup.procs path does not exist
+    # in our synthetic tree → unknown.
+    assert result.scope is None
+    assert result.agent_kind == AGENT_UNKNOWN
+
+
+def test_scope_procs_missing_is_unknown(host: _FakeHost) -> None:
+    """Pane cgroup resolves to a scope, but the scope's cgroup.procs is gone.
+
+    Simulates the session ending between the pane read and the procs read:
+    the scope basename is still reported, but agent_kind is `unknown`.
+    """
+    scope = "tmuxctl-git-ended.scope"
+    host.add_proc(810001, scope=scope, comm="bash", cmdline="/bin/bash -l")
+    # Deliberately do NOT call set_scope_procs — no cgroup.procs file.
+    result = _classify(host, 810001)
+    assert result.scope == scope
+    assert result.agent_kind == AGENT_UNKNOWN
+
+
+def test_proc_vanishes_between_enumeration_and_read(host: _FakeHost) -> None:
+    """A pid listed in cgroup.procs but with no /proc entry is skipped.
+
+    The classifier must not crash when a pid races away after the
+    cgroup.procs read; it skips it and still classifies the survivors.
+    """
+    scope = "tmuxctl-git-race.scope"
+    host.add_proc(820001, scope=scope, comm="bash", cmdline="/bin/bash -l")
+    host.add_proc(
+        820003, scope=scope, comm="claude", cmdline="claude --skip"
+    )
+    # 820002 is listed but never created → simulates a vanished pid.
+    host.set_scope_procs(scope, [820001, 820002, 820003])
+
+    result = _classify(host, 820001)
+    assert result.agent_kind == AGENT_CLAUDE
+    assert result.evidence_pid == 820003
+
+
+# ---------------------------------------------------------------------------
+# kind_for_panes — the batch entry the RPC calls
+# ---------------------------------------------------------------------------
+
+
+def test_batch_classifies_each_pane_and_isolates_failures(
+    host: _FakeHost,
+) -> None:
+    """One bad pane (invalid pane_pid) must not sink the rest of the batch."""
+    claude_scope = "tmuxctl-git-pocketshell.scope"
+    host.add_proc(100, scope=claude_scope, comm="bash", cmdline="/bin/bash")
+    host.add_proc(101, scope=claude_scope, comm="claude", cmdline="claude")
+    host.set_scope_procs(claude_scope, [100, 101])
+
+    shell_scope = "tmuxctl-git-plain.scope"
+    host.add_proc(200, scope=shell_scope, comm="bash", cmdline="/bin/bash")
+    host.set_scope_procs(shell_scope, [200])
+
+    panes = [
+        {"pane_id": "%1", "pane_pid": 100},
+        {"pane_id": "%2", "pane_pid": 200},
+        {"pane_id": "%3", "pane_pid": "not-an-int"},  # bad pane
+        {"pane_id": "%4"},  # missing pane_pid entirely
+    ]
+    results = cgroup_agents.kind_for_panes(
+        panes,
+        proc_root=str(host.proc_root),
+        cgroup_mount=str(host.cgroup_mount),
+    )
+
+    by_id = {r["pane_id"]: r for r in results}
+    assert by_id["%1"]["agent_kind"] == AGENT_CLAUDE
+    assert by_id["%1"]["scope"] == claude_scope
+    assert by_id["%1"]["evidence_pid"] == 101
+    assert by_id["%2"]["agent_kind"] == AGENT_NONE
+    assert by_id["%2"]["scope"] == shell_scope
+    # Bad / missing panes degrade to unknown, never raise.
+    assert by_id["%3"]["agent_kind"] == AGENT_UNKNOWN
+    assert by_id["%3"]["scope"] is None
+    assert by_id["%4"]["agent_kind"] == AGENT_UNKNOWN
+
+
+def test_batch_pane_id_passthrough_and_correlation(host: _FakeHost) -> None:
+    """pane_id is passed through verbatim so the client can correlate."""
+    scope = "tmuxctl-git-pocketshell.scope"
+    host.add_proc(300, scope=scope, comm="bash", cmdline="/bin/bash")
+    host.add_proc(301, scope=scope, comm="claude", cmdline="claude")
+    host.set_scope_procs(scope, [300, 301])
+
+    results = cgroup_agents.kind_for_panes(
+        [{"pane_id": "%99", "pane_pid": 300}],
+        proc_root=str(host.proc_root),
+        cgroup_mount=str(host.cgroup_mount),
+    )
+    assert results[0]["pane_id"] == "%99"
+    assert results[0]["agent_kind"] == AGENT_CLAUDE
+
+
+def test_batch_empty_panes() -> None:
+    assert cgroup_agents.kind_for_panes([]) == []
+
+
+def test_result_json_omits_evidence_pid_when_absent(host: _FakeHost) -> None:
+    """The `none` result envelope has no evidence_pid key (compact wire)."""
+    scope = "tmuxctl-git-empty.scope"
+    host.add_proc(400, scope=scope, comm="bash", cmdline="/bin/bash")
+    host.set_scope_procs(scope, [400])
+    results = cgroup_agents.kind_for_panes(
+        [{"pane_id": "%1", "pane_pid": 400}],
+        proc_root=str(host.proc_root),
+        cgroup_mount=str(host.cgroup_mount),
+    )
+    assert "evidence_pid" not in results[0]
+    assert results[0]["agent_kind"] == AGENT_NONE

{pocketshell-0.4.6 → pocketshell-0.4.8}/tests/test_daemon.py

@@ -836,6 +836,63 @@ def test_daemon_registry_includes_sessions_and_jobs_methods() -> None:
     assert daemon_mod.METHOD_CACHE_INVALIDATIONS["jobs.trigger"] == ("jobs.list",)
 
 
+def test_daemon_registry_includes_agents_kind_for_panes() -> None:
+    assert "agents.kind_for_panes" in daemon_mod.DEFAULT_METHODS
+    # No TTL: agent processes change live, so the method must never be cached
+    # (the spike explicitly forbids a TTL cache here — procs change live).
+    assert "agents.kind_for_panes" not in daemon_mod.METHOD_TTLS
+
+
+def test_agents_kind_for_panes_round_trip(
+    running_daemon: subprocess.Popen,
+    sandbox_socket: Path,
+) -> None:
+    """The RPC returns a well-formed batch envelope over the real transport.
+
+    A pane_pid that does not exist resolves to ``unknown`` (never an error),
+    and the pane_id is passed through verbatim so the client can correlate.
+    This exercises the full JSON-RPC framing + handler dispatch, not just the
+    in-process classifier.
+    """
+    result = daemon_mod.call(
+        "agents.kind_for_panes",
+        {"panes": [{"pane_id": "%1", "pane_pid": 999999999}]},
+        socket_path=sandbox_socket,
+    )
+    assert isinstance(result, dict)
+    assert isinstance(result["results"], list)
+    assert len(result["results"]) == 1
+    entry = result["results"][0]
+    assert entry["pane_id"] == "%1"
+    # A non-existent pid resolves to `unknown` (no /proc entry), never errors.
+    assert entry["agent_kind"] == "unknown"
+    assert entry["scope"] is None
+
+
+def test_agents_kind_for_panes_rejects_non_list_panes(
+    running_daemon: subprocess.Popen,
+    sandbox_socket: Path,
+) -> None:
+    """A `panes` param that is not a list is an invalid-params error."""
+    with pytest.raises(RuntimeError, match="must be a list"):
+        daemon_mod.call(
+            "agents.kind_for_panes",
+            {"panes": "not-a-list"},
+            socket_path=sandbox_socket,
+        )
+
+
+def test_agents_kind_for_panes_empty_when_no_panes(
+    running_daemon: subprocess.Popen,
+    sandbox_socket: Path,
+) -> None:
+    """Omitting `panes` yields an empty results list, not an error."""
+    result = daemon_mod.call(
+        "agents.kind_for_panes", {}, socket_path=sandbox_socket
+    )
+    assert result == {"results": []}
+
+
 def test_failed_usage_fetch_is_not_cached(
     sandbox_socket: Path,
     tmp_path: Path,