cc-session-control 0.4.0__py3-none-any.whl

cc_session_control/data/proc.py

@@ -0,0 +1,214 @@
+"""The only module that touches `/proc` — Linux/WSL liveness primitives.
+
+Everything here degrades safely off Linux (no `/proc`): `proc_starttime`
+returns None, `pid_alive` returns False, and `ancestor_pids` returns just this
+process. Callers use `has_proc()` to detect the degraded mode and (in later
+phases) refuse destructive ops when the "current" session can't be determined.
+"""
+
+from __future__ import annotations
+
+import os
+import shlex
+from dataclasses import dataclass
+
+_PROC = "/proc"
+
+
+@dataclass
+class ProcRC:
+    """A /proc-discovered Claude project RC server (`claude remote-control`).
+
+    Internal to this module — the public, view-facing model is `RCServer`
+    (assembled in `data/rc.py` after classifying managed vs external). `pid` is
+    0 when produced by the pure matcher (the scanner fills it); `cwd` comes from
+    `readlink(/proc/<pid>/cwd)`.
+    """
+    pid: int
+    name: str = ""
+    cwd: str = ""
+
+
+def has_proc() -> bool:
+    """True if `/proc` is readable (Linux/WSL). Liveness degrades when False."""
+    return os.path.isdir(_PROC)
+
+
+def current_determinable() -> bool:
+    """Whether the "current" (csctl-launching) session can be determined.
+
+    Needs `/proc` to walk the ancestor pid chain. When False (e.g. macOS), we
+    cannot tell which session launched csctl, so callers MUST refuse destructive
+    ops — terminate/delete/cleanup could otherwise hit the launching session
+    (R10). This is the single predicate the data/action layers gate on.
+    """
+    return has_proc()
+
+
+def proc_starttime(pid: int) -> str | None:
+    """Field 22 (starttime) from `/proc/<pid>/stat`, or None if unavailable.
+
+    The comm field (field 2) is wrapped in parens and may itself contain spaces
+    or parens, so we slice AFTER the last ')' before splitting — a naive
+    `split()[21]` would break on such names. Returns the raw string so it can be
+    compared directly against the `procStart` string in `sessions/<pid>.json`.
+    """
+    if not has_proc():
+        return None
+    try:
+        with open(f"{_PROC}/{pid}/stat") as fh:
+            data = fh.read()
+    except Exception:
+        return None
+    try:
+        # `after` begins at field 3 (state); field 22 is at index 22 - 3.
+        after = data[data.rfind(")") + 2:]
+        return after.split()[22 - 3]
+    except Exception:
+        return None
+
+
+def pid_alive(pid: int | None, proc_start: str | None) -> bool:
+    """True iff `/proc/<pid>` exists AND its starttime matches `proc_start`.
+
+    The starttime match defeats pid reuse (a recycled pid has a newer
+    starttime). When `proc_start` is unknown we fall back to mere existence.
+    Always False on non-Linux / missing `/proc`, so liveness degrades.
+    """
+    if not pid:
+        return False
+    st = proc_starttime(pid)
+    if st is None:
+        return False
+    if not proc_start:
+        return True
+    return st == proc_start
+
+
+def ancestor_pids() -> set[int]:
+    """csctl's own ancestor pid chain (including self).
+
+    A session whose pid is in this set is the "current" one (it launched
+    csctl) and is protected. Linux/WSL only — returns just `{getpid()}` when
+    `/proc` is unavailable, in which case current can't be determined and
+    callers must degrade (see R10).
+    """
+    pids = {os.getpid()}
+    if not has_proc():
+        return pids
+    pid = os.getpid()
+    for _ in range(40):
+        try:
+            with open(f"{_PROC}/{pid}/stat") as fh:
+                data = fh.read()
+            ppid = int(data[data.rfind(")") + 2:].split()[1])
+        except Exception:
+            break
+        if ppid <= 1:
+            break
+        pids.add(ppid)
+        pid = ppid
+    return pids
+
+
+# --- project RC server discovery (R5 / D5) ---------------------------------
+# A real `claude remote-control --name <name>` server's /proc cmdline shows the
+# FULL argv (verified live: a bare interactive `claude` instead collapses its
+# cmdline to just `claude`), so we match on the argv SHAPE, not on `comm` (a
+# node-launched claude can have comm `node`). Other tools are excluded — codex
+# runs `--remote-control` as a FLAG with argv0 `codex` and no `remote-control`
+# subcommand token, so it never matches.
+
+
+def _split_cmdline(cmdline: str) -> list[str]:
+    """Split a `/proc/<pid>/cmdline` string into argv.
+
+    Real cmdlines are NUL-separated (with a trailing NUL). A space-joined string
+    (test convenience / odd launchers) is tolerated by falling back to a shell
+    split when no NUL boundaries are present.
+    """
+    parts = [p for p in cmdline.split("\0") if p]
+    if len(parts) <= 1 and cmdline.strip() and " " in cmdline.strip():
+        try:
+            parts = shlex.split(cmdline)
+        except ValueError:
+            parts = cmdline.split()
+    return parts
+
+
+def _flag_value(argv: list[str], flag: str) -> str | None:
+    """Value of `--flag value` or `--flag=value` in argv; None if absent/empty."""
+    prefix = flag + "="
+    for i, tok in enumerate(argv):
+        if tok == flag:
+            return argv[i + 1] if i + 1 < len(argv) else None
+        if tok.startswith(prefix):
+            return tok[len(prefix):] or None
+    return None
+
+
+def _match_rc_cmdline(comm: str, cmdline: str) -> ProcRC | None:
+    """PURE matcher (no IO): is this argv a Claude project RC server? (AC5)
+
+    Matches iff the program basename is `claude` AND a bare `remote-control`
+    subcommand token is present AND a `--name <name>` flag is parseable. `comm`
+    is accepted for signature completeness but deliberately NOT trusted on its
+    own. Returns a `ProcRC` (pid=0, filled by the scanner) or None.
+    """
+    argv = _split_cmdline(cmdline)
+    if not argv:
+        return None
+    if os.path.basename(argv[0]) != "claude":
+        return None
+    if "remote-control" not in argv[1:]:
+        return None
+    name = _flag_value(argv, "--name")
+    if not name:
+        return None
+    return ProcRC(pid=0, name=name)
+
+
+def _read_text(path: str) -> str:
+    try:
+        with open(path, errors="ignore") as fh:
+            return fh.read()
+    except Exception:
+        return ""
+
+
+def _read_link(path: str) -> str:
+    try:
+        return os.readlink(path)
+    except Exception:
+        return ""
+
+
+def scan_rc_servers() -> list[ProcRC]:
+    """Walk `/proc` for Claude project RC server processes (R5).
+
+    Reads each pid's `comm` + `cmdline`, runs the pure `_match_rc_cmdline`, and
+    fills `pid` + `cwd` (`readlink /proc/<pid>/cwd`) for matches. Degrades to
+    `[]` off Linux (no `/proc`) and swallows all per-pid errors.
+    """
+    if not has_proc():
+        return []
+    servers: list[ProcRC] = []
+    try:
+        entries = os.listdir(_PROC)
+    except Exception:
+        return []
+    for entry in entries:
+        if not entry.isdigit():
+            continue
+        try:
+            pid = int(entry)
+            comm = _read_text(f"{_PROC}/{pid}/comm").strip()
+            cmdline = _read_text(f"{_PROC}/{pid}/cmdline")
+            match = _match_rc_cmdline(comm, cmdline)
+            if match is None:
+                continue
+            cwd = _read_link(f"{_PROC}/{pid}/cwd")
+            servers.append(ProcRC(pid=pid, name=match.name, cwd=cwd or match.cwd))
+        except Exception:
+            continue
+    return servers

cc_session_control/data/rc.py

@@ -0,0 +1,411 @@
+"""RC workspace management — manage Claude Code Remote Control via tmux."""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import shlex
+import subprocess
+import time
+
+from ..config import cfg
+from ..models import EnvRecord, RCProject, RCServer
+from . import environments, proc
+
+# Cloud bridge env id printed to a managed server's pane (`environment=env_…`).
+_ENV_ID_RE = re.compile(r"env_[A-Za-z0-9]+")
+
+
+def _ensure_list() -> None:
+    os.makedirs(cfg.config_dir, exist_ok=True)
+    if not cfg.rc_list.is_file():
+        cfg.rc_list.touch()
+
+
+def list_enabled() -> list[str]:
+    _ensure_list()
+    try:
+        return [
+            line.strip() for line in cfg.rc_list.read_text().splitlines()
+            if line.strip() and not line.strip().startswith("#")
+        ]
+    except FileNotFoundError:
+        return []
+
+
+def list_has(proj: str) -> bool:
+    return proj in list_enabled()
+
+
+def list_add(proj: str) -> None:
+    _ensure_list()
+    if list_has(proj):
+        return
+    with open(cfg.rc_list, "a") as f:
+        f.write(f"{proj}\n")
+
+
+def list_rm(proj: str) -> None:
+    _ensure_list()
+    try:
+        lines = cfg.rc_list.read_text().splitlines(keepends=True)
+        with open(cfg.rc_list, "w") as f:
+            for line in lines:
+                if line.strip() != proj:
+                    f.write(line)
+    except FileNotFoundError:
+        pass
+
+
+def toggle_autostart(proj: str) -> bool:
+    """Toggle project in the autostart list. Returns new state."""
+    if list_has(proj):
+        list_rm(proj)
+        return False
+    list_add(proj)
+    return True
+
+
+def _load_projects() -> dict:
+    """Read the `projects` map from ~/.claude.json, or {} on any failure.
+
+    Single source for the claude.json read shared by trusted_projects /
+    is_trusted, so the open+parse+swallow dance lives in one place.
+    """
+    try:
+        with open(cfg.claude_json) as f:
+            return json.load(f).get("projects", {}) or {}
+    except Exception:
+        return {}
+
+
+def trusted_projects() -> list[str]:
+    prefix = str(cfg.workspace) + "/"
+    projects = []
+    try:
+        for key, val in _load_projects().items():
+            if val.get("hasTrustDialogAccepted") and key.startswith(prefix):
+                name = key[len(prefix):]
+                if "/" not in name:
+                    projects.append(name)
+    except Exception:
+        return []
+    return sorted(projects)
+
+
+def is_trusted(proj: str) -> bool:
+    try:
+        key = f"{cfg.workspace}/{proj}"
+        return bool(_load_projects().get(key, {}).get("hasTrustDialogAccepted", False))
+    except Exception:
+        return False
+
+
+# --- tmux adapter ---------------------------------------------------------
+# Single seam over the tmux CLI. Only `_tmux_run` touches `subprocess`; every
+# other tmux call routes through a verb wrapper. Each wrapper keeps the
+# swallow-errors contract (return empty/False/None on any failure).
+
+
+def _tmux_run(args: list[str]) -> subprocess.CompletedProcess | None:
+    """Run one `tmux <args>` command; return the result, or None on failure."""
+    try:
+        return subprocess.run(
+            ["tmux", *args],
+            capture_output=True, text=True, timeout=5,
+        )
+    except Exception:
+        return None
+
+
+def _tmux_list_windows() -> list[str]:
+    cp = _tmux_run(["list-windows", "-t", cfg.rc_session, "-F", "#W"])
+    if cp is None:
+        return []
+    return [line.strip() for line in cp.stdout.splitlines() if line.strip()]
+
+
+def _tmux_pane_alive(target: str) -> bool:
+    cp = _tmux_run(["list-panes", "-t", target, "-F", "#{pane_dead}"])
+    if cp is None:
+        return False
+    return cp.stdout.strip().split("\n")[0] == "0"
+
+
+def _tmux_window_pids() -> dict[str, int]:
+    """{window_name: pane_pid} for the rc session; {} on failure.
+
+    The pane pid IS the RC server pid because `start_one` runs `exec claude …`
+    (the shell is replaced). Used to classify /proc-discovered servers as
+    managed (pid in this set) vs external.
+    """
+    cp = _tmux_run(
+        ["list-windows", "-t", cfg.rc_session, "-F", "#W\t#{pane_pid}"]
+    )
+    if cp is None:
+        return {}
+    out: dict[str, int] = {}
+    for line in cp.stdout.splitlines():
+        name, _, pid_s = line.partition("\t")
+        name = name.strip()
+        try:
+            pid = int(pid_s.strip())
+        except ValueError:
+            continue
+        if name:
+            out[name] = pid
+    return out
+
+
+def _tmux_capture_pane(target: str) -> str:
+    """Full scrollback of a tmux pane as text; "" on failure.
+
+    Captures from the start of history (`-S -`) so an `env_*` id printed at
+    server startup is still grep-able after it scrolls off the visible region.
+    """
+    cp = _tmux_run(["capture-pane", "-p", "-S", "-", "-t", target])
+    if cp is None:
+        return ""
+    return cp.stdout
+
+
+def _tmux_has_session(session: str) -> bool:
+    cp = _tmux_run(["has-session", "-t", session])
+    return cp is not None and cp.returncode == 0
+
+
+def _tmux_new_window(session: str, name: str, cmd: str) -> bool:
+    cp = _tmux_run(["new-window", "-t", session, "-n", name, cmd])
+    return cp is not None and cp.returncode == 0
+
+
+def _tmux_new_session(session: str, name: str, cmd: str) -> bool:
+    cp = _tmux_run(["new-session", "-d", "-s", session, "-n", name, cmd])
+    return cp is not None and cp.returncode == 0
+
+
+def _tmux_kill_window(target: str) -> bool:
+    cp = _tmux_run(["kill-window", "-t", target])
+    return cp is not None and cp.returncode == 0
+
+
+def _tmux_kill_session(session: str) -> bool:
+    cp = _tmux_run(["kill-session", "-t", session])
+    return cp is not None and cp.returncode == 0
+
+
+def _tmux_windows() -> list[str]:
+    return _tmux_list_windows()
+
+
+def _is_alive(proj: str) -> bool:
+    return _tmux_pane_alive(f"{cfg.rc_session}:{proj}")
+
+
+def run_in_tmux(session: str, window: str, cmd: str) -> bool:
+    """Run `cmd` in a tmux `window` under `session`, creating the session if
+    it doesn't exist yet. Public seam for relaunching a session outside the
+    managed RC server machinery."""
+    if _tmux_has_session(session):
+        return _tmux_new_window(session, window, cmd)
+    return _tmux_new_session(session, window, cmd)
+
+
+def _read_rc_at_startup(directory: str) -> bool | None:
+    for name in ("settings.local.json", "settings.json"):
+        path = os.path.join(directory, ".claude", name)
+        try:
+            with open(path) as f:
+                val = json.load(f).get("remoteControlAtStartup")
+            if val is not None:
+                return bool(val)
+        except Exception:
+            continue
+    return None
+
+
+def _read_spawn_mode(proj: str) -> str | None:
+    """Project `remoteControlSpawnMode` from ~/.claude.json, or None if unset.
+
+    Lives in the same `projects` map as `hasTrustDialogAccepted` (verified on
+    disk), so it reuses `_load_projects` rather than re-opening claude.json.
+    """
+    try:
+        key = f"{cfg.workspace}/{proj}"
+        val = _load_projects().get(key, {}).get("remoteControlSpawnMode")
+        return str(val) if val else None
+    except Exception:
+        return None
+
+
+def set_rc_at_startup(directory: str, value: bool | None) -> None:
+    settings_dir = os.path.join(directory, ".claude")
+    path = os.path.join(settings_dir, "settings.local.json")
+    os.makedirs(settings_dir, exist_ok=True)
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except Exception:
+        data = {}
+    if value is None:
+        data.pop("remoteControlAtStartup", None)
+    else:
+        data["remoteControlAtStartup"] = value
+    with open(path, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+
+
+def scan() -> list[RCProject]:
+    enabled = set(list_enabled())
+    trusted = trusted_projects()
+    windows = set(_tmux_windows())
+    all_names = sorted(set(trusted) | enabled)
+
+    result: list[RCProject] = []
+    for name in all_names:
+        directory = str(cfg.workspace / name)
+        in_windows = name in windows
+        if in_windows:
+            status = "running" if _is_alive(name) else "dead"
+        else:
+            status = "stopped"
+        result.append(RCProject(
+            name=name, directory=directory,
+            trusted=name in trusted,
+            in_list=name in enabled,
+            status=status,
+            auto_start=name in enabled,
+            rc_at_startup=_read_rc_at_startup(directory),
+            spawn_mode=_read_spawn_mode(name),
+        ))
+    return result
+
+
+def _split_env(env_id: str) -> tuple[str, str]:
+    """`env_abc` -> (`env`, `abc`); ("", "") when not a namespaced id."""
+    prefix, sep, suffix = env_id.partition("_")
+    if not sep or not prefix or not suffix:
+        return "", ""
+    return prefix, suffix
+
+
+def _capture_env_id(target: str) -> str:
+    """Grep an `env_*` cloud id from a managed server's pane output, or "".
+
+    The project RC server leaves zero structured footprint; its cloud env id is
+    only printed to stdout (`environment=env_…`). This is the single signal we
+    can capture locally for the ledger.
+    """
+    m = _ENV_ID_RE.search(_tmux_capture_pane(target))
+    return m.group(0) if m else ""
+
+
+def scan_servers() -> list[RCServer]:
+    """All project RC servers: managed (csctl tmux) ∪ external (/proc) — R5/D5.
+
+    Managed = tmux windows in `cfg.rc_session` (their pane pid IS the server
+    pid); external = `/proc`-discovered `claude remote-control --name` processes
+    NOT owned by a managed pane. External servers are READ-ONLY (no
+    takeover/restart — review gate; sustains the "no auto-restart RC" rule).
+
+    For managed servers the captured `env_*` cloud id is pushed one-way into the
+    ledger via `environments.upsert` (rc → environments only; environments never
+    imports rc). Swallows errors → returns whatever it assembled.
+    """
+    try:
+        window_pids = _tmux_window_pids()
+        discovered = proc.scan_rc_servers()
+    except Exception:
+        return []
+
+    by_pid = {p.pid: p for p in discovered}
+    managed_pid_set = set(window_pids.values())
+
+    servers: list[RCServer] = []
+    env_records: list[EnvRecord] = []
+
+    # Managed windows first — tmux is the authority for "managed".
+    for window, pid in window_pids.items():
+        target = f"{cfg.rc_session}:{window}"
+        status = "running" if _tmux_pane_alive(target) else "dead"
+        found = by_pid.get(pid)
+        env_id = _capture_env_id(target)
+        if env_id:
+            prefix, key = _split_env(env_id)
+            if prefix and key:
+                env_records.append(EnvRecord(prefix=prefix, key=key, bound_sid=None))
+        servers.append(RCServer(
+            name=found.name if found else window,
+            cwd=found.cwd if found else "",
+            managed=True,
+            pid=pid or None,
+            env_id=env_id or None,
+            status=status,
+        ))
+
+    # External — discovered procs not owned by any managed pane.
+    for p in discovered:
+        if p.pid in managed_pid_set:
+            continue
+        servers.append(RCServer(
+            name=p.name, cwd=p.cwd, managed=False,
+            pid=p.pid or None, env_id=None, status="running",
+        ))
+
+    if env_records:
+        environments.upsert(env_records)
+    return servers
+
+
+def start_one(proj: str) -> bool:
+    directory = cfg.workspace / proj
+    if not directory.is_dir():
+        return False
+    if not is_trusted(proj):
+        return False
+    if proj in _tmux_windows():
+        if _is_alive(proj):
+            return False
+        if not stop_one(proj):
+            return False
+
+    remote_name = f"ws/{proj}"
+    # Each fresh Remote Control process registers a distinct cloud environment.
+    # Keep restart explicit so transient exits do not pile up duplicate mobile
+    # environment entries with the same display name.
+    cmd = (
+        f"cd {shlex.quote(str(directory))} && exec claude remote-control "
+        f"--name {shlex.quote(remote_name)} --spawn same-dir"
+    )
+
+    session = cfg.rc_session
+    has_session = _tmux_has_session(session)
+
+    if has_session:
+        return _tmux_new_window(session, proj, cmd)
+    return _tmux_new_session(session, proj, cmd)
+
+
+def stop_one(proj: str) -> bool:
+    return _tmux_kill_window(f"{cfg.rc_session}:{proj}")
+
+
+def stop_all() -> bool:
+    return _tmux_kill_session(cfg.rc_session)
+
+
+def start_many(projects: list[str]) -> int:
+    count = 0
+    for proj in projects:
+        if count > 0:
+            time.sleep(cfg.rc_stagger)
+        if start_one(proj):
+            count += 1
+    return count
+
+
+def start_all_listed() -> int:
+    """Start every project currently enabled in the autostart list."""
+    return start_many(list_enabled())