pocketshell 0.4.8__tar.gz → 0.4.9__tar.gz

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

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

{pocketshell-0.4.8 → pocketshell-0.4.9}/src/pocketshell/agents.py

@@ -74,6 +74,7 @@ from __future__ import annotations
 import json
 import os
 import shutil
+import subprocess
 from pathlib import Path
 from typing import Optional
 
@@ -354,6 +355,56 @@ def _resolve_dir(ctx: click.Context, directory: str) -> Path:
     return path
 
 
+def record_agent_kind(
+    kind: str,
+    env: Optional[dict[str, str]] = None,
+    runner=None,
+) -> bool:
+    """Record the launched agent ``kind`` as a per-session tmux user option.
+
+    Workstream A / epic #821: the durable "what is this session running"
+    state lives **host-side** as the tmux user option ``@ps_agent_kind`` on
+    the session this wrapper runs in. Writing it here (in the same process
+    that becomes the agent) means the recorded kind cannot drift from what
+    actually launched, and it covers every launch caller — the folder
+    picker, the assistant, the repo browser — with zero Kotlin launch-exec
+    change. The client reads it back through its session enumeration
+    (``tmux list-sessions -F '…#{@ps_agent_kind}'``).
+
+    The option is session-scoped (not global): ``tmux set-option`` without
+    ``-g`` sets it on the current session, which is the session the agent
+    was launched into. tmux session options persist for the life of the
+    session, so the recorded kind survives reconnect / app restart /
+    app-kill / reinstall — exactly the durability the epic requires.
+
+    No-op (returns ``False``) when not running inside tmux (``$TMUX``
+    unset) — e.g. a bare SSH ``pocketshell agent`` invocation — or when the
+    kind is unknown. A failure of the ``tmux`` call is swallowed: recording
+    the kind must never prevent the agent from launching.
+
+    ``runner`` is injected so tests can assert the exact ``tmux`` argv
+    without spawning a real process; production passes ``None`` and it
+    resolves to :func:`subprocess.run`.
+    """
+    if not kind:
+        return False
+    source_env = os.environ if env is None else env
+    if not source_env.get("TMUX"):
+        # Not inside a tmux server — nothing to record onto.
+        return False
+    if runner is None:
+        runner = subprocess.run
+    try:
+        runner(
+            ["tmux", "set-option", "@ps_agent_kind", kind],
+            check=False,
+        )
+    except Exception:
+        # Recording the kind is best-effort; never block the launch on it.
+        return False
+    return True
+
+
 def launch_agent(
     ctx: click.Context,
     kind: str,
@@ -363,6 +414,7 @@ def launch_agent(
     config_dir: Optional[str],
     extra_env: Optional[dict[str, str]] = None,
     execvpe=None,
+    record_kind=None,
 ) -> None:
     """Resolve the dir, build env+argv, suppress prompts, exec the agent.
 
@@ -376,9 +428,17 @@ def launch_agent(
     ``os`` so a monkeypatch on ``agents.os.execvpe`` is honoured (a default
     argument would bind the original at def-time and bypass the patch).
     :func:`os.execvpe` never returns on success.
+
+    Before the exec, when running inside tmux, the launched ``kind`` is
+    recorded as the per-session ``@ps_agent_kind`` user option
+    (:func:`record_agent_kind`) so the client can read the agent type back
+    from the host without output-parsing detection (epic #821 Workstream A).
+    ``record_kind`` is injected the same way as ``execvpe`` for tests.
     """
     if execvpe is None:
         execvpe = os.execvpe
+    if record_kind is None:
+        record_kind = record_agent_kind
 
     path = _resolve_dir(ctx, directory)
     resolved_dir = str(path)
@@ -409,6 +469,12 @@ def launch_agent(
     if kind == "claude":
         seed_claude_trust(claude_config_path(env), resolved_dir)
 
+    # Record the launched kind on the tmux session BEFORE the exec replaces
+    # this process (epic #821 Workstream A). Use this wrapper's own
+    # environment (os.environ) for the TMUX detection — `env` is the
+    # provider-stripped launch env that does not necessarily carry $TMUX.
+    record_kind(kind, dict(os.environ))
+
     # Replace this process with the agent so it owns the pty cleanly.
     execvpe(argv[0], argv, env)
 

pocketshell-0.4.9/src/pocketshell/agents_kind.py

@@ -0,0 +1,216 @@
+"""`pocketshell agents kind` — CLI seam over the cgroup agent-kind detector.
+
+Epic #821 (workstream A2-infra). The daemon RPC ``agents.kind_for_panes``
+(:func:`pocketshell.cgroup_agents.kind_for_panes`,
+:func:`pocketshell.daemon._agents_kind_for_panes_handler`) does cgroup-v2 +
+``/proc`` agent-kind detection on the host, but it is **daemon-registry-only**:
+the PocketShell Android client only ever execs ``pocketshell <subcommand>`` over
+its warm SSH session — it never speaks JSON-RPC directly. So the detection has
+no way to be reached from the client today.
+
+This module adds the missing seam: ``pocketshell agents kind`` accepts a pane
+list (each pane ``{pane_id, pane_pid}``, matching the RPC's input shape),
+dispatches to the daemon when it is up (mirroring the
+:func:`pocketshell.jobs._try_daemon_jobs_call` CLI→daemon pattern), falls back
+to calling :func:`pocketshell.cgroup_agents.kind_for_panes` in-process when the
+daemon is absent (the detection is pure cgroupfs/``/proc`` reads — no shell-out,
+so the in-process call is the same computation the daemon performs), and emits
+the RPC's ``{"results": [{pane_id, agent_kind, scope, evidence_pid?}]}`` as
+stable, client-parseable JSON on stdout.
+
+Input forms (pick whichever is convenient — they merge):
+
+- **stdin JSON** — ``{"panes": [{"pane_id": "%1", "pane_pid": 2647034}, ...]}``,
+  byte-for-byte the RPC request shape. This is the primary form the client uses
+  (it pipes the pane snapshot it already has).
+- **``--pane PANE_ID=PANE_PID``** (repeatable) — an ergonomic alternative for a
+  one-shot SSH exec / manual debugging.
+
+``none`` / ``unknown`` / empty-pane inputs never error: an empty pane list
+yields ``{"results": []}``, a missing/invalid ``pane_pid`` yields
+``agent_kind="unknown"`` for that pane, and one bad pane never sinks the batch
+(the detector is defensive by design — see ``cgroup_agents``).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any, Mapping, Optional
+
+import click
+
+from pocketshell.cgroup_agents import (
+    DEFAULT_CGROUP_MOUNT,
+    DEFAULT_PROC_ROOT,
+)
+
+
+def _parse_stdin_panes() -> list[dict[str, Any]]:
+    """Read ``{"panes": [...]}`` from stdin, returning the pane list.
+
+    A non-TTY empty stdin (the common ``--pane``-only or no-input case) yields
+    an empty list rather than an error. Malformed JSON is a clear usage error.
+    """
+    if sys.stdin is None or sys.stdin.isatty():
+        return []
+    raw = sys.stdin.read()
+    if not raw.strip():
+        return []
+    try:
+        doc = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        raise click.ClickException(
+            f"agents kind: stdin is not valid JSON: {exc}"
+        ) from exc
+    if not isinstance(doc, Mapping):
+        raise click.ClickException(
+            "agents kind: stdin JSON must be an object with a `panes` list"
+        )
+    raw_panes = doc.get("panes")
+    if raw_panes is None:
+        return []
+    if not isinstance(raw_panes, list):
+        raise click.ClickException(
+            "agents kind: `panes` must be a list of objects"
+        )
+    return [dict(p) for p in raw_panes if isinstance(p, Mapping)]
+
+
+def _parse_pane_options(pane_specs: tuple[str, ...]) -> list[dict[str, Any]]:
+    """Parse ``--pane PANE_ID=PANE_PID`` specs into pane mappings.
+
+    ``PANE_PID`` is left as the raw string; the detector coerces it to ``int``
+    and degrades an invalid value to ``agent_kind="unknown"`` rather than
+    failing — so a non-numeric pid here is not a CLI error, mirroring the RPC.
+    """
+    panes: list[dict[str, Any]] = []
+    for spec in pane_specs:
+        pane_id, sep, pane_pid = spec.partition("=")
+        if not sep:
+            raise click.ClickException(
+                f"agents kind: --pane must be PANE_ID=PANE_PID (got {spec!r})"
+            )
+        panes.append({"pane_id": pane_id, "pane_pid": pane_pid})
+    return panes
+
+
+def _try_daemon_call(
+    panes: list[dict[str, Any]],
+    *,
+    proc_root: str,
+    cgroup_mount: str,
+    timeout: float = 5.0,
+) -> Optional[dict[str, Any]]:
+    """Dispatch ``agents.kind_for_panes`` to the daemon; ``None`` on miss/error.
+
+    Mirrors :func:`pocketshell.jobs._try_daemon_jobs_call`. Only used when the
+    detection runs against the real host roots — when the caller overrode
+    ``--proc-root`` / ``--cgroup-mount`` (tests, debugging), the in-process path
+    is used directly so the override is honoured (the daemon reads the live
+    host roots and cannot see a synthetic tree).
+    """
+    if proc_root != DEFAULT_PROC_ROOT or cgroup_mount != DEFAULT_CGROUP_MOUNT:
+        return None
+
+    from pocketshell import daemon as _daemon
+
+    socket_path = _daemon.resolve_socket_path()
+    if not socket_path.exists():
+        return None
+    try:
+        result = _daemon.call(
+            "agents.kind_for_panes",
+            params={"panes": panes},
+            socket_path=socket_path,
+            timeout=timeout,
+        )
+    except (_daemon.DaemonClientError, RuntimeError, OSError):
+        return None
+    if not isinstance(result, dict) or "results" not in result:
+        return None
+    return result
+
+
+def _classify_in_process(
+    panes: list[dict[str, Any]],
+    *,
+    proc_root: str,
+    cgroup_mount: str,
+) -> dict[str, Any]:
+    """Call the detector in-process and wrap it in the RPC's result envelope."""
+    from pocketshell import cgroup_agents as _cgroup_agents
+
+    results = _cgroup_agents.kind_for_panes(
+        panes, proc_root=proc_root, cgroup_mount=cgroup_mount
+    )
+    return {"results": results}
+
+
+@click.group(
+    name="agents",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "Host-side agent-awareness helpers for the PocketShell client.\n\n"
+        "`kind` classifies the coding-agent (claude / codex / opencode) "
+        "running in each tmux pane's cgroup scope — the CLI seam over the "
+        "`agents.kind_for_panes` daemon RPC. See epic #821."
+    ),
+)
+def agents_group() -> None:
+    """Top-level `agents` group registered onto the root `pocketshell` CLI."""
+
+
+@agents_group.command(
+    name="kind",
+    context_settings={"help_option_names": ["-h", "--help"]},
+    help=(
+        "Classify the agent kind in each pane's cgroup scope.\n\n"
+        "Reads a pane list as `{\"panes\": [{\"pane_id\", \"pane_pid\"}, ...]}` "
+        "JSON on stdin (the RPC request shape), and/or via repeatable "
+        "`--pane PANE_ID=PANE_PID`. Emits "
+        "`{\"results\": [{\"pane_id\", \"agent_kind\", \"scope\", "
+        "\"evidence_pid\"?}]}` as JSON on stdout. `agent_kind` is one of "
+        "claude / codex / opencode / none (scope, no agent) / unknown "
+        "(pane pid/cgroup unreadable). Empty input -> `{\"results\": []}`."
+    ),
+)
+@click.option(
+    "--pane",
+    "pane_specs",
+    multiple=True,
+    metavar="PANE_ID=PANE_PID",
+    help=(
+        "A pane to classify, as PANE_ID=PANE_PID. Repeatable. Merges with any "
+        "panes read from stdin JSON."
+    ),
+)
+@click.option(
+    "--proc-root",
+    default=DEFAULT_PROC_ROOT,
+    show_default=True,
+    help="Override the /proc root (testing / debugging).",
+)
+@click.option(
+    "--cgroup-mount",
+    default=DEFAULT_CGROUP_MOUNT,
+    show_default=True,
+    help="Override the cgroup v2 mount point (testing / debugging).",
+)
+def agents_kind_command(
+    pane_specs: tuple[str, ...],
+    proc_root: str,
+    cgroup_mount: str,
+) -> None:
+    """Classify the agent kind running in each pane's cgroup scope."""
+    panes = _parse_stdin_panes() + _parse_pane_options(pane_specs)
+
+    envelope = _try_daemon_call(
+        panes, proc_root=proc_root, cgroup_mount=cgroup_mount
+    )
+    if envelope is None:
+        envelope = _classify_in_process(
+            panes, proc_root=proc_root, cgroup_mount=cgroup_mount
+        )
+
+    click.echo(json.dumps(envelope))

{pocketshell-0.4.8 → pocketshell-0.4.9}/src/pocketshell/cli.py

@@ -24,6 +24,7 @@ import click
 from pocketshell import __version__
 from pocketshell.agent_log import agent_log_command
 from pocketshell.agents import agent_group
+from pocketshell.agents_kind import agents_group
 from pocketshell.env import env_group
 from pocketshell.github import github_group
 from pocketshell.hooks import hooks_group
@@ -55,6 +56,7 @@ def cli() -> None:
 
 cli.add_command(usage_command, name="usage")
 cli.add_command(agent_group, name="agent")
+cli.add_command(agents_group, name="agents")
 cli.add_command(profiles_group, name="profiles")
 cli.add_command(jobs_group, name="jobs")
 cli.add_command(sessions_group, name="sessions")

{pocketshell-0.4.8 → pocketshell-0.4.9}/tests/test_agents.py

@@ -453,6 +453,122 @@ def test_launch_agent_missing_dir_exits_two():
     assert exc.value.exit_code == 2
 
 
+# ---------------------------------------------------------------------------
+# Record agent kind as the host-side @ps_agent_kind tmux user option
+# (epic #821 Workstream A). The wrapper writes the launched kind onto the
+# tmux session it runs in, so the client reads the type back from the host
+# without output-parsing detection.
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize("kind", ["claude", "codex", "opencode"])
+def test_record_agent_kind_sets_session_option_inside_tmux(kind):
+    calls = []
+    ok = agents.record_agent_kind(
+        kind,
+        env={"TMUX": "/tmp/tmux-1000/default,1234,0"},
+        runner=lambda argv, **kw: calls.append((argv, kw)),
+    )
+    assert ok is True
+    assert len(calls) == 1
+    argv, _kw = calls[0]
+    # Session-scoped (no -g): tmux applies it to the current session, which
+    # is the one the agent was launched into.
+    assert argv == ["tmux", "set-option", "@ps_agent_kind", kind]
+
+
+def test_record_agent_kind_noop_when_not_in_tmux():
+    calls = []
+    ok = agents.record_agent_kind(
+        "claude",
+        env={},  # $TMUX unset -> bare SSH invocation
+        runner=lambda argv, **kw: calls.append(argv),
+    )
+    assert ok is False
+    assert calls == []
+
+
+def test_record_agent_kind_noop_for_blank_kind():
+    calls = []
+    ok = agents.record_agent_kind(
+        "",
+        env={"TMUX": "x"},
+        runner=lambda argv, **kw: calls.append(argv),
+    )
+    assert ok is False
+    assert calls == []
+
+
+def test_record_agent_kind_swallows_runner_failure():
+    def boom(argv, **kw):
+        raise RuntimeError("tmux not found")
+
+    # A failure to record must never propagate (the agent must still launch).
+    ok = agents.record_agent_kind(
+        "codex",
+        env={"TMUX": "x"},
+        runner=boom,
+    )
+    assert ok is False
+
+
+@pytest.mark.parametrize("kind", ["claude", "codex", "opencode"])
+def test_launch_agent_records_kind_before_exec(tmp_path, monkeypatch, kind):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("TMUX", "/tmp/tmux-1000/default,1234,0")
+    order = []
+
+    def fake_record(k, env=None, runner=None):
+        order.append(("record", k, env.get("TMUX") if env else None))
+        return True
+
+    def fake_execvpe(file, argv, env):
+        order.append(("exec", file))
+
+    agents.launch_agent(
+        _FakeCtx(),
+        kind,
+        str(tmp_path),
+        skip_permissions=True,
+        config_dir=None,
+        execvpe=fake_execvpe,
+        record_kind=fake_record,
+    )
+    # The kind is recorded with the wrapper's own $TMUX, and recorded BEFORE
+    # the exec replaces the process.
+    assert order == [
+        ("record", kind, "/tmp/tmux-1000/default,1234,0"),
+        ("exec", kind),
+    ]
+
+
+def test_launch_agent_execs_even_when_record_is_noop(tmp_path, monkeypatch):
+    # When recording is a no-op (e.g. not inside tmux -> record returns
+    # False), the agent must still exec normally. Production
+    # record_agent_kind swallows its own errors and returns False rather
+    # than raising (covered by test_record_agent_kind_swallows_runner_failure),
+    # so the launch is never blocked by a recording problem.
+    monkeypatch.setenv("HOME", str(tmp_path))
+    captured = {}
+
+    def quiet_record(k, env=None, runner=None):
+        return False
+
+    def fake_execvpe(file, argv, env):
+        captured["file"] = file
+
+    agents.launch_agent(
+        _FakeCtx(),
+        "codex",
+        str(tmp_path),
+        skip_permissions=True,
+        config_dir=None,
+        execvpe=fake_execvpe,
+        record_kind=quiet_record,
+    )
+    assert captured["file"] == "codex"
+
+
 # ---------------------------------------------------------------------------
 # Missing agent binary -> friendly 127 (issue #774 §3)
 #

pocketshell-0.4.9/tests/test_agents_kind.py

@@ -0,0 +1,332 @@
+"""Tests for the ``pocketshell agents kind`` CLI subcommand (epic #821 A2-infra).
+
+The subcommand is the missing CLI seam over the daemon RPC
+``agents.kind_for_panes`` (``cgroup_agents.kind_for_panes``): the PocketShell
+Android client only ever execs ``pocketshell <subcommand>`` over its warm SSH
+session — it never speaks JSON-RPC — so the cgroup/scope agent-kind detection
+needs a subcommand to reach it. ``pocketshell agents kind`` accepts a pane list
+(matching the RPC's ``{pane_id, pane_pid}`` shape), classifies each pane, and
+emits the RPC's ``{"results": [...]}`` envelope as stable JSON on stdout.
+
+These tests point the classifier at a synthetic ``/proc`` + cgroup-v2 tree
+(reusing the same fake-host shape as ``test_cgroup_agents``) via the injectable
+``--proc-root`` / ``--cgroup-mount`` options, so they exercise the real
+classifier with zero live sessions, covering the claude / codex / opencode /
+none / unknown / empty cases.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Iterator, Optional
+
+import pytest
+from click.testing import CliRunner
+
+from pocketshell import daemon as daemon_mod
+from pocketshell.cli import cli
+
+
+# ---------------------------------------------------------------------------
+# Synthetic-filesystem fixture builder (mirrors test_cgroup_agents._FakeHost)
+# ---------------------------------------------------------------------------
+
+
+class _FakeHost:
+    """Builds a synthetic ``/proc`` + cgroup-v2 tree under ``tmp_path``."""
+
+    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:
+        proc_dir = self.proc_root / str(pid)
+        proc_dir.mkdir(parents=True, exist_ok=True)
+        if scope is None:
+            rel = "/user.slice/user-1000.slice/session-3.scope"
+        else:
+            rel = self._scope_relpath(scope)
+        (proc_dir / "cgroup").write_text(f"0::{rel}\n", encoding="utf-8")
+        (proc_dir / "comm").write_text(comm + "\n", encoding="utf-8")
+        (proc_dir / "cmdline").write_text(
+            cmdline.replace(" ", "\0") + "\0", encoding="utf-8"
+        )
+
+    def add_scope(self, scope: str, pids: list[int]) -> None:
+        scope_dir = self.cgroup_mount / self._scope_relpath(scope).lstrip("/")
+        scope_dir.mkdir(parents=True, exist_ok=True)
+        (scope_dir / "cgroup.procs").write_text(
+            "".join(f"{p}\n" for p in pids), encoding="utf-8"
+        )
+
+
+def _seed_claude(host: _FakeHost) -> None:
+    host.add_proc(
+        1001, scope="tmuxctl-claude-main.scope", comm="bash", cmdline="-bash"
+    )
+    host.add_proc(
+        1002,
+        scope="tmuxctl-claude-main.scope",
+        comm="claude",
+        cmdline="claude",
+    )
+    host.add_scope("tmuxctl-claude-main.scope", [1001, 1002])
+
+
+def _seed_codex(host: _FakeHost) -> None:
+    host.add_proc(
+        2001, scope="tmuxctl-codex.scope", comm="bash", cmdline="-bash"
+    )
+    host.add_proc(
+        2002,
+        scope="tmuxctl-codex.scope",
+        comm="MainThread",
+        cmdline="node /usr/lib/node_modules/codex/bin/codex.js",
+    )
+    host.add_scope("tmuxctl-codex.scope", [2001, 2002])
+
+
+def _seed_opencode(host: _FakeHost) -> None:
+    host.add_proc(
+        3001, scope="tmuxctl-opencode-lab.scope", comm="bash", cmdline="-bash"
+    )
+    host.add_proc(
+        3002,
+        scope="tmuxctl-opencode-lab.scope",
+        comm="opencode",
+        cmdline="opencode",
+    )
+    host.add_scope("tmuxctl-opencode-lab.scope", [3001, 3002])
+
+
+def _seed_plain_shell(host: _FakeHost) -> None:
+    """A pane that resolves to a scope but runs no agent -> ``none``."""
+    host.add_proc(
+        4001, scope="tmuxctl-shell.scope", comm="bash", cmdline="-bash"
+    )
+    host.add_scope("tmuxctl-shell.scope", [4001])
+
+
+def _invoke(panes: list[dict], host: _FakeHost) -> dict:
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "agents",
+            "kind",
+            "--proc-root",
+            str(host.proc_root),
+            "--cgroup-mount",
+            str(host.cgroup_mount),
+        ],
+        input=json.dumps({"panes": panes}),
+    )
+    assert result.exit_code == 0, result.output
+    return json.loads(result.output)
+
+
+def test_help_lists_the_kind_subcommand() -> None:
+    runner = CliRunner()
+    result = runner.invoke(cli, ["agents", "kind", "--help"])
+    assert result.exit_code == 0, result.output
+    assert "kind" in result.output.lower()
+
+
+def test_classifies_claude(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    _seed_claude(host)
+    out = _invoke([{"pane_id": "%1", "pane_pid": 1001}], host)
+    results = out["results"]
+    assert len(results) == 1
+    assert results[0]["pane_id"] == "%1"
+    assert results[0]["agent_kind"] == "claude"
+    assert results[0]["scope"] == "tmuxctl-claude-main.scope"
+    assert results[0]["evidence_pid"] == 1002
+
+
+def test_classifies_codex_node_wrapped(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    _seed_codex(host)
+    out = _invoke([{"pane_id": "%2", "pane_pid": 2001}], host)
+    assert out["results"][0]["agent_kind"] == "codex"
+    assert out["results"][0]["scope"] == "tmuxctl-codex.scope"
+
+
+def test_classifies_opencode(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    _seed_opencode(host)
+    out = _invoke([{"pane_id": "%3", "pane_pid": 3001}], host)
+    assert out["results"][0]["agent_kind"] == "opencode"
+
+
+def test_plain_shell_resolves_to_none(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    _seed_plain_shell(host)
+    out = _invoke([{"pane_id": "%4", "pane_pid": 4001}], host)
+    assert out["results"][0]["agent_kind"] == "none"
+    assert out["results"][0]["scope"] == "tmuxctl-shell.scope"
+
+
+def test_unreadable_pane_resolves_to_unknown(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    # pid 9999 has no /proc entry -> cgroup unreadable -> unknown.
+    out = _invoke([{"pane_id": "%9", "pane_pid": 9999}], host)
+    assert out["results"][0]["agent_kind"] == "unknown"
+
+
+def test_missing_pane_pid_is_unknown_not_error(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    out = _invoke([{"pane_id": "%5"}], host)
+    assert out["results"][0]["agent_kind"] == "unknown"
+    assert out["results"][0]["pane_id"] == "%5"
+
+
+def test_empty_pane_list_returns_empty_results(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    out = _invoke([], host)
+    assert out == {"results": []}
+
+
+def test_no_stdin_no_panes_returns_empty_results() -> None:
+    runner = CliRunner()
+    result = runner.invoke(cli, ["agents", "kind"], input="")
+    assert result.exit_code == 0, result.output
+    assert json.loads(result.output) == {"results": []}
+
+
+def test_mixed_batch_one_bad_pane_does_not_sink_others(tmp_path: Path) -> None:
+    host = _FakeHost(tmp_path)
+    _seed_claude(host)
+    _seed_codex(host)
+    out = _invoke(
+        [
+            {"pane_id": "%1", "pane_pid": 1001},
+            {"pane_id": "%bad", "pane_pid": "not-an-int"},
+            {"pane_id": "%2", "pane_pid": 2001},
+        ],
+        host,
+    )
+    kinds = {r["pane_id"]: r["agent_kind"] for r in out["results"]}
+    assert kinds["%1"] == "claude"
+    assert kinds["%bad"] == "unknown"
+    assert kinds["%2"] == "codex"
+
+
+# ---------------------------------------------------------------------------
+# CLI -> daemon round-trip (proves the daemon RPC path, not just in-process)
+# ---------------------------------------------------------------------------
+
+
+def _spawn_daemon(socket_path: Path) -> subprocess.Popen:
+    env = dict(os.environ)
+    env["POCKETSHELL_DAEMON_SOCKET"] = str(socket_path)
+    env["POCKETSHELL_DAEMON_IDLE_SECS"] = "120"
+    proc = subprocess.Popen(
+        [sys.executable, "-m", "pocketshell", "daemon", "_serve"],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=env,
+        start_new_session=True,
+    )
+    assert daemon_mod.wait_until_ready(socket_path=socket_path, deadline=10.0), (
+        proc.stderr.read().decode(errors="replace") if proc.stderr else ""
+    )
+    return proc
+
+
+@pytest.fixture()
+def running_daemon(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> Iterator[Path]:
+    socket_path = tmp_path / "ps-agents-kind.sock"
+    monkeypatch.setenv("POCKETSHELL_DAEMON_SOCKET", str(socket_path))
+    proc = _spawn_daemon(socket_path)
+    try:
+        yield socket_path
+    finally:
+        if proc.poll() is None:
+            proc.send_signal(signal.SIGTERM)
+            try:
+                proc.wait(timeout=5.0)
+            except subprocess.TimeoutExpired:
+                proc.kill()
+                proc.wait(timeout=2.0)
+        for path in (socket_path, socket_path.with_suffix(".pid")):
+            try:
+                path.unlink()
+            except FileNotFoundError:
+                pass
+
+
+def test_cli_reaches_daemon_rpc(
+    running_daemon: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """When a daemon is up on the default roots, the CLI dispatches to the
+    ``agents.kind_for_panes`` RPC instead of computing in-process.
+
+    Proven by sabotaging the in-process classifier *in the CLI process* so a
+    well-formed envelope can only have come from the daemon subprocess (a
+    separate process whose classifier is intact).
+    """
+    def _boom(*_a, **_k):
+        raise AssertionError("in-process classifier must not run when daemon up")
+
+    monkeypatch.setattr(
+        "pocketshell.cgroup_agents.kind_for_panes", _boom
+    )
+    # The daemon classifies against the live host; pid 1 always exists, so the
+    # envelope is well-formed regardless of what scope it resolves to.
+    runner = CliRunner()
+    result = runner.invoke(
+        cli, ["agents", "kind", "--pane", "%live=1"]
+    )
+    assert result.exit_code == 0, result.output
+    out = json.loads(result.output)
+    assert out["results"][0]["pane_id"] == "%live"
+    assert "agent_kind" in out["results"][0]
+
+
+def test_pane_option_form(tmp_path: Path) -> None:
+    """The ``--pane PANE_ID=PANE_PID`` repeatable form is an ergonomic
+    alternative to stdin JSON for a one-shot SSH exec."""
+    host = _FakeHost(tmp_path)
+    _seed_claude(host)
+    runner = CliRunner()
+    result = runner.invoke(
+        cli,
+        [
+            "agents",
+            "kind",
+            "--proc-root",
+            str(host.proc_root),
+            "--cgroup-mount",
+            str(host.cgroup_mount),
+            "--pane",
+            "%1=1001",
+        ],
+    )
+    assert result.exit_code == 0, result.output
+    out = json.loads(result.output)
+    assert out["results"][0]["pane_id"] == "%1"
+    assert out["results"][0]["agent_kind"] == "claude"