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

cc_session_control/data/environments.py

@@ -0,0 +1,444 @@
+"""Bridge-environment ledger — a PASSIVE, observe-and-forget store (R6, D4).
+
+Claude Code keeps only the *current* bridge binding for a session/agent (a
+single overwritten field), so toggled-away or historically minted cloud
+environments vanish from on-disk state. csctl maintains its own append-only
+ledger so those environments stay traceable enough to be deleted by hand on
+claude.ai/code — there is NO local deregister, this module never deletes a
+cloud environment.
+
+Design invariants:
+  - **Passive store.** Callers push observations in (`upsert(records)`); this
+    module never reaches up to collect them. It must NOT import `rc`
+    (`environments` is below `rc` in the import DAG; `rc` calls `upsert` one-way
+    in Phase 5 for the `env_*` namespace). `observe()` is a convenience builder
+    that reads the lower-level `registry` (and accepts `env_*` records passed in,
+    never collected here).
+  - **Two observation tiers.** `observe()` is the bridge-truthy FILE-REFERENCED
+    set — what defines ledger MEMBERSHIP (an env exists in the cloud while any
+    on-disk file references it, alive or zombie). `observe_live()` alive-gates the
+    same sources for the CURRENT/bound DISPLAY. Orphans (manual-delete
+    candidates) are `ledger − file-referenced`: an env the ledger remembers but no
+    file references anymore (RC toggled off, job removed, server stopped).
+  - **Three namespaces, namespace-scoped dedup.** The merge key is
+    `(prefix, key)`: within `cse_*` a resume pair shares one suffix → one env;
+    `session_*` and `cse_*` never merge (their suffixes never coincide in
+    practice); `env_*` ids are opaque and each unique. Dedup is WITHIN a
+    namespace, never cross-view.
+  - **Write-on-change + atomic + single-writer.** The read-modify-write runs
+    under an advisory `flock` (degrades gracefully where unavailable), the
+    resulting ledger is serialized canonically and only rewritten when it
+    differs from disk, and the write is `tmp + os.replace` atomic.
+  - **Retention/compaction.** Entries older than `_RETENTION_SECONDS` (90d) are
+    dropped; if still over `_MAX_ENTRIES`, the most-recently-seen are kept. A
+    re-observed env always carries `last_seen == now` so it survives compaction.
+
+Everything swallows errors → safe empties: a missing or corrupt ledger never
+crashes (returns `[]` / no-ops).
+
+Known limitation (capability red line): the ledger cannot back-fill
+environments minted while csctl was not running — there is no `null`/history on
+disk to recover them — so the orphan / manual-delete list is inherently
+incomplete.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import os
+from collections.abc import Iterator
+from dataclasses import replace
+from typing import Any
+
+from ..config import cfg
+from ..models import AgentJob, BridgeEnv, EnvRecord, RCServer, SessionProc
+from . import proc, registry
+
+try:  # POSIX advisory locking; absent on Windows → degrade to no lock.
+    import fcntl
+except ImportError:  # pragma: no cover - platform dependent
+    fcntl = None  # type: ignore[assignment]
+
+# Drop entries unseen for longer than this; cap total entries beyond that.
+_RETENTION_SECONDS = 90 * 86400
+_MAX_ENTRIES = 500
+
+
+# --- bridge id parsing -----------------------------------------------------
+
+def _split_bridge(bridge: str) -> tuple[str, str]:
+    """`cse_abc` -> (`cse`, `abc`); the suffix is the namespace-local env id."""
+    prefix, sep, suffix = bridge.partition("_")
+    if not sep:
+        return "", ""
+    return prefix, suffix
+
+
+# --- observation builder (reads registry only, never rc) -------------------
+
+def observe(
+    session_procs: list[SessionProc] | None = None,
+    agent_jobs: list[AgentJob] | None = None,
+    rc_servers: list[RCServer] | None = None,
+    max_age: float = 5.0,
+) -> list[EnvRecord]:
+    """FILE-REFERENCED bridge envs — the ledger MEMBERSHIP set (R6).
+
+    Every env an on-disk file references right now: a session's truthy
+    `bridgeSessionId` (`session_*`, alive OR zombie), a job's `cse_*` env suffix,
+    plus any `env_*` captured from the `rc_servers` passed in. This is the set
+    that DEFINES ledger membership — an env exists in the cloud as long as a file
+    references it, regardless of liveness. Contrast `observe_live()`, which
+    alive-gates the same sources for the CURRENT/bound display; orphans are
+    `ledger − file-referenced`.
+
+    Pure when the sources are supplied (snapshot path / tests); self-reads the
+    registry when they are None (CLI / no-snapshot fallback). `env_*` is only ever
+    passed in (this module never imports rc). Swallows errors → [].
+    """
+    try:
+        if session_procs is None:
+            session_procs = registry.read_session_procs(max_age=max_age)
+        if agent_jobs is None:
+            agent_jobs = registry.read_agent_jobs(max_age=max_age)
+        records: list[EnvRecord] = []
+        for sp in session_procs:
+            if not sp.bridge:
+                continue
+            prefix, key = _split_bridge(sp.bridge)
+            if prefix and key:
+                records.append(EnvRecord(prefix=prefix, key=key, bound_sid=sp.sid))
+        for job in agent_jobs:
+            if job.env_suffix:
+                records.append(
+                    EnvRecord(prefix="cse", key=job.env_suffix, bound_sid=job.sid)
+                )
+        for srv in rc_servers or []:
+            if srv.env_id:
+                prefix, sep, key = srv.env_id.partition("_")
+                if sep and prefix and key:
+                    records.append(EnvRecord(prefix=prefix, key=key, bound_sid=None))
+        return records
+    except Exception:
+        return []
+
+
+def observe_live(
+    session_procs: list[SessionProc] | None = None,
+    agent_jobs: list[AgentJob] | None = None,
+    rc_servers: list[RCServer] | None = None,
+    max_age: float = 5.0,
+) -> list[EnvRecord]:
+    """Alive-gated "currently exposed" bridge envs (R3/R6) — the CURRENT set.
+
+    Where `observe()` is a bridge-truthy passive collector, this lifts the
+    `_is_rc_exposed` predicate to the env ledger: a bridge is CURRENT only when
+    its owner is alive — `session_*` gated by proc-alive, `cse_*` by a proc-alive
+    session sharing the job sid (host-alive), `env_*` by a running RC server. So a
+    zombie session's stale `bridgeSessionId` is NOT reported as current — it falls
+    through to `orphan_envs` (a manual-delete candidate) instead of overstating
+    the bound count.
+
+    Pure when `session_procs`/`agent_jobs` are supplied (the snapshot path passes
+    its already-liveness-resolved data — DI for tests); reads the registry +
+    `/proc` itself when they are None (CLI / no-snapshot view fallback). Swallows
+    errors → [].
+    """
+    try:
+        if session_procs is None:
+            session_procs = [
+                replace(sp, proc_alive=proc.pid_alive(sp.pid, sp.proc_start))
+                for sp in registry.read_session_procs(max_age=max_age)
+            ]
+        if agent_jobs is None:
+            agent_jobs = registry.read_agent_jobs(max_age=max_age)
+        alive_sids = {sp.sid for sp in session_procs if sp.proc_alive}
+        records: list[EnvRecord] = []
+        for sp in session_procs:
+            if sp.bridge and sp.proc_alive:
+                prefix, key = _split_bridge(sp.bridge)
+                if prefix and key:
+                    records.append(EnvRecord(prefix=prefix, key=key, bound_sid=sp.sid))
+        for job in agent_jobs:
+            if job.env_suffix and (job.host_alive or job.sid in alive_sids):
+                records.append(
+                    EnvRecord(prefix="cse", key=job.env_suffix, bound_sid=job.sid)
+                )
+        for srv in rc_servers or []:
+            if srv.env_id and srv.status == "running":
+                prefix, sep, key = srv.env_id.partition("_")
+                if sep and prefix and key:
+                    records.append(EnvRecord(prefix=prefix, key=key, bound_sid=None))
+        return records
+    except Exception:
+        return []
+
+
+# --- ledger IO (parse / serialize / atomic write / lock) -------------------
+
+def _read_raw() -> str:
+    try:
+        with open(cfg.environments_ledger, errors="ignore") as fh:
+            return fh.read()
+    except Exception:
+        return ""
+
+
+def _parse_ledger(text: str) -> dict[tuple[str, str], BridgeEnv]:
+    """Parse ledger text into a (prefix, key) -> BridgeEnv map. Skips bad lines.
+
+    Persisted `status` is ignored (recomputed against the live observation), so
+    only the five durable fields are read back.
+    """
+    out: dict[tuple[str, str], BridgeEnv] = {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            d = json.loads(line)
+        except Exception:
+            continue
+        prefix = d.get("prefix")
+        key = d.get("key")
+        if not prefix or not key:
+            continue
+        out[(prefix, key)] = BridgeEnv(
+            prefix=str(prefix),
+            key=str(key),
+            bound_sid=d.get("bound_sid"),
+            first_seen=_as_float(d.get("first_seen")),
+            last_seen=_as_float(d.get("last_seen")),
+        )
+    return out
+
+
+def _as_float(v: Any) -> float:
+    try:
+        return float(v)
+    except (TypeError, ValueError):
+        return 0.0
+
+
+def _serialize(entries: list[BridgeEnv]) -> str:
+    """Canonical JSONL (sorted by id, sorted keys) so write-on-change is exact."""
+    lines: list[str] = []
+    for e in sorted(entries, key=lambda e: (e.prefix, e.key)):
+        d = {
+            "prefix": e.prefix,
+            "key": e.key,
+            "bound_sid": e.bound_sid,
+            "first_seen": e.first_seen,
+            "last_seen": e.last_seen,
+        }
+        lines.append(json.dumps(d, sort_keys=True, ensure_ascii=False))
+    return ("\n".join(lines) + "\n") if lines else ""
+
+
+def _atomic_write(text: str) -> None:
+    cfg.config_dir.mkdir(parents=True, exist_ok=True)
+    path = str(cfg.environments_ledger)
+    tmp = path + ".tmp"
+    with open(tmp, "w") as fh:
+        fh.write(text)
+        fh.flush()
+        os.fsync(fh.fileno())
+    os.replace(tmp, path)
+
+
+@contextlib.contextmanager
+def _write_lock() -> Iterator[None]:
+    """Advisory single-writer lock around a read-modify-write.
+
+    Uses a dedicated `.lock` file (never replaced) so the lock survives the
+    ledger's atomic `os.replace`. Degrades to no-op locking where `fcntl` is
+    unavailable (Windows) — the atomic rename still prevents a torn file.
+    """
+    fh = None
+    try:
+        cfg.config_dir.mkdir(parents=True, exist_ok=True)
+        fh = open(str(cfg.environments_ledger) + ".lock", "w")
+        if fcntl is not None:
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+            except Exception:
+                pass
+        yield
+    except Exception:
+        yield
+    finally:
+        if fh is not None:
+            if fcntl is not None:
+                try:
+                    fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+                except Exception:
+                    pass
+            fh.close()
+
+
+# --- merge / compaction ----------------------------------------------------
+
+def _dedup_records(records: list[EnvRecord]) -> list[EnvRecord]:
+    """Collapse records by (prefix, key) — within-namespace dedup (resume pairs).
+
+    Picks a deterministic canonical `bound_sid` (the smallest non-empty sid) so
+    the merge result is stable regardless of the observation order (registry
+    glob order is not sorted), keeping write-on-change from flapping.
+    """
+    grouped: dict[tuple[str, str], list[EnvRecord]] = {}
+    for r in records:
+        if not r.prefix or not r.key:
+            continue
+        grouped.setdefault((r.prefix, r.key), []).append(r)
+    out: list[EnvRecord] = []
+    for (prefix, key), recs in grouped.items():
+        sids = sorted({r.bound_sid for r in recs if r.bound_sid})
+        out.append(EnvRecord(prefix=prefix, key=key, bound_sid=sids[0] if sids else None))
+    return out
+
+
+def _merge(
+    ledger: dict[tuple[str, str], BridgeEnv],
+    records: list[EnvRecord],
+    now: float,
+) -> dict[tuple[str, str], BridgeEnv]:
+    for rec in _dedup_records(records):
+        k = (rec.prefix, rec.key)
+        existing = ledger.get(k)
+        if existing is None:
+            ledger[k] = BridgeEnv(
+                prefix=rec.prefix,
+                key=rec.key,
+                bound_sid=rec.bound_sid,
+                first_seen=now,
+                last_seen=now,
+            )
+        else:
+            existing.bound_sid = rec.bound_sid
+            existing.last_seen = now
+    return ledger
+
+
+def _membership(ledger: dict[tuple[str, str], BridgeEnv]) -> set[tuple[str, str, str | None, float]]:
+    """Durable identity of the ledger, EXCLUDING `last_seen` (M2).
+
+    Two ledgers with the same membership but different `last_seen` are
+    write-equivalent: re-observing the same envs must not rewrite the file just
+    because the clock advanced. `first_seen` and `bound_sid` ARE part of identity
+    (a new entry, a dropped entry, or a resume re-bind is a real change).
+    """
+    return {(e.prefix, e.key, e.bound_sid, e.first_seen) for e in ledger.values()}
+
+
+def _compact(
+    ledger: dict[tuple[str, str], BridgeEnv], now: float
+) -> dict[tuple[str, str], BridgeEnv]:
+    cutoff = now - _RETENTION_SECONDS
+    kept = {k: e for k, e in ledger.items() if e.last_seen >= cutoff}
+    if len(kept) > _MAX_ENTRIES:
+        newest = sorted(kept.values(), key=lambda e: e.last_seen, reverse=True)
+        kept = {(e.prefix, e.key): e for e in newest[:_MAX_ENTRIES]}
+    return kept
+
+
+# --- public API ------------------------------------------------------------
+
+def upsert(records: list[EnvRecord], now: float | None = None) -> None:
+    """Merge observed env records into the ledger (passive store, R6/D4).
+
+    Sets `first_seen` on insert, advances `last_seen` to `now` on re-observation
+    (`now` injectable for deterministic tests), dedups within a namespace, and
+    compacts — all under an advisory lock, via an atomic `tmp + replace`.
+
+    Write-on-change ignores `last_seen` (M2): the file is rewritten only when the
+    MEMBERSHIP changes (an env added/dropped, a re-bind, a new `first_seen`) or
+    when the on-disk text is not already canonical (corrupt / legacy line cleanup).
+    A pure clock advance on otherwise-identical membership does NOT rewrite, so a
+    steady-state refresh cycle leaves the file (and its mtime) untouched. The
+    persisted copy still carries the advanced `last_seen` whenever a real write
+    happens. Swallows all errors.
+    """
+    import time
+
+    ts = time.time() if now is None else now
+    try:
+        with _write_lock():
+            old_text = _read_raw()
+            ledger = _parse_ledger(old_text)
+            # Snapshot identity BEFORE _merge mutates bound_sid/last_seen in place.
+            old_sig = _membership(ledger)
+            non_canonical = _serialize(list(ledger.values())) != old_text
+            ledger = _merge(ledger, records, ts)
+            ledger = _compact(ledger, ts)
+            if _membership(ledger) != old_sig or non_canonical:
+                _atomic_write(_serialize(list(ledger.values())))
+    except Exception:
+        return
+
+
+def _read_ledger() -> dict[tuple[str, str], BridgeEnv]:
+    return _parse_ledger(_read_raw())
+
+
+def current_envs(observed: list[EnvRecord]) -> list[BridgeEnv]:
+    """Envs bound to something observed right now (status='current').
+
+    Classifies the ledger against the observation. An observed env not yet in
+    the ledger (caller queried before `upsert`) is still reported current so the
+    result is correct regardless of call order. Sorted newest-seen first.
+    """
+    obs = {(r.prefix, r.key): r for r in observed if r.prefix and r.key}
+    ledger = _read_ledger()
+    out: list[BridgeEnv] = []
+    seen: set[tuple[str, str]] = set()
+    for k, env in ledger.items():
+        if k in obs:
+            env.status = "current"
+            out.append(env)
+            seen.add(k)
+    for k, rec in obs.items():
+        if k not in seen:
+            out.append(BridgeEnv(prefix=rec.prefix, key=rec.key,
+                                 bound_sid=rec.bound_sid, status="current"))
+    return sorted(out, key=lambda e: e.last_seen, reverse=True)
+
+
+def orphan_envs(observed: list[EnvRecord]) -> list[BridgeEnv]:
+    """Ledger entries NOT in the current observation (status='orphan').
+
+    Pass the FILE-REFERENCED set (`observe()`) here so orphans are precisely
+    `ledger − file-referenced`: envs the ledger remembers but no on-disk file
+    references anymore (RC toggled off, job removed, server stopped). These are
+    the manual-delete candidates: csctl cannot deregister a cloud environment, so
+    the user removes them on claude.ai/code. Sorted newest-seen first.
+    (Inherently incomplete — see the module docstring's red line.)
+    """
+    obs_keys = {(r.prefix, r.key) for r in observed if r.prefix and r.key}
+    out: list[BridgeEnv] = []
+    for k, env in _read_ledger().items():
+        if k not in obs_keys:
+            env.status = "orphan"
+            out.append(env)
+    return sorted(out, key=lambda e: e.last_seen, reverse=True)
+
+
+def manual_delete_list(observed: list[EnvRecord] | None = None) -> list[dict[str, Any]]:
+    """Orphans formatted for manual deletion on claude.ai/code (R6).
+
+    Each row carries the full namespaced `env_id` (incl. `env_*`), `prefix`,
+    `key`, last-known `bound_sid`, and `last_seen`. With no observation passed,
+    every ledger entry is treated as a candidate. There is NO deregister action
+    — this is a checklist for the human, observe-and-forget only.
+    """
+    orphans = orphan_envs(observed or [])
+    return [
+        {
+            "env_id": e.env_id,
+            "prefix": e.prefix,
+            "key": e.key,
+            "bound_sid": e.bound_sid,
+            "last_seen": e.last_seen,
+        }
+        for e in orphans
+    ]

cc_session_control/data/liveness.py

@@ -0,0 +1,140 @@
+"""Session liveness — the single authority.
+
+Owns the ONE module-global cache for `claude agents --json` (mirrored by the
+`agents.py` re-export shim so terminate's invalidate and scan's read share it).
+`live_index` is a pure merge of already-fetched liveness inputs (registry
+session files with injected proc liveness + `claude agents --json`).
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import time
+
+from ..models import LiveInfo, SessionProc
+
+_cache: dict[str, int | None] | None = None
+_cache_time: float = 0.0
+
+
+def alive_map(max_age: float = 5.0) -> dict[str, int | None]:
+    """Return {session_id: pid} for all known agents. Cached for max_age seconds."""
+    global _cache, _cache_time
+    now = time.monotonic()
+    if _cache is not None and (now - _cache_time) < max_age:
+        return _cache
+    try:
+        out = subprocess.run(
+            ["claude", "agents", "--json"],
+            capture_output=True, text=True, timeout=10,
+        ).stdout
+        result = {
+            a.get("sessionId"): a.get("pid")
+            for a in json.loads(out or "[]")
+            if a.get("sessionId")
+        }
+    except Exception:
+        result = {}
+    _cache = result
+    _cache_time = now
+    return result
+
+
+def invalidate_cache() -> None:
+    global _cache
+    _cache = None
+
+
+def _source_of(entrypoint: str, kind: str) -> str:
+    """Coarse source bucket from the registry entrypoint/kind (D9)."""
+    if kind == "bg":
+        return "bg"
+    if entrypoint == "claude-vscode":
+        return "vscode"
+    if entrypoint == "sdk-ts":
+        return "sdk"
+    return "cli"
+
+
+def _is_rc_exposed(bridge: str | None, pid_alive: bool) -> bool:
+    """Whether session remote control is CURRENTLY exposed (pure predicate).
+
+    Exposed iff the bridge id is a truthy string AND the owning process is still
+    alive. This correctly collapses the three bridge states — key absent (None),
+    opened-then-closed (null/None, transient), and exposing (a `session_*`
+    string) — crossed with alive/dead. The single authority for "currently
+    exposed" (R3/AC3). No IO; inputs injected.
+    """
+    return bool(bridge) and pid_alive
+
+
+def _start_key(proc_start: str) -> int:
+    try:
+        return int(proc_start)
+    except (TypeError, ValueError):
+        return -1
+
+
+def live_index(
+    session_procs: list[SessionProc],
+    agents_map: dict[str, int | None],
+) -> dict[str, LiveInfo]:
+    """PURE merge of registry session files + `claude agents --json`.
+
+    Groups `session_procs` by sessionId (resume keeps the sid, mints a new pid),
+    picks the injected proc-alive pid (newest `procStart` when several), and
+    marks liveness. Falls back to `agents_map` when there is no proc-confirmed
+    runtime — on non-Linux all `proc_alive` values are False, so a sid present in
+    `agents_map` is still reported alive (degraded liveness). No IO; inputs are
+    injected.
+    """
+    index: dict[str, LiveInfo] = {}
+
+    by_sid: dict[str, list[SessionProc]] = {}
+    for sp in session_procs:
+        by_sid.setdefault(sp.sid, []).append(sp)
+
+    for sid, procs in by_sid.items():
+        alive_procs = [p for p in procs if p.proc_alive]
+        if alive_procs:
+            chosen = max(alive_procs, key=lambda p: _start_key(p.proc_start))
+            alive = True
+            # All alive pids, not just the newest — "current" must protect any
+            # ancestor pid of a resumed (multi-pid) sid.
+            pids = [p.pid for p in alive_procs]
+        else:
+            chosen = max(procs, key=lambda p: _start_key(p.proc_start))
+            alive = False
+            pids = []
+        index[sid] = LiveInfo(
+            sid=sid,
+            pid=chosen.pid if alive else None,
+            proc_start=chosen.proc_start,
+            status=chosen.status,
+            kind=chosen.kind,
+            entrypoint=chosen.entrypoint,
+            bridge=chosen.bridge,
+            source=_source_of(chosen.entrypoint, chosen.kind),
+            alive=alive,
+            proc_alive=alive,
+            pids=pids,
+        )
+
+    # `claude agents --json` is authoritative for liveness: it covers agent-only
+    # sids and rescues the degraded (no-/proc) path.
+    for sid, pid in agents_map.items():
+        if not sid:
+            continue
+        info = index.get(sid)
+        if info is None:
+            index[sid] = LiveInfo(
+                sid=sid, pid=pid, alive=True, pids=[pid] if pid else []
+            )
+            continue
+        info.alive = True
+        if info.pid is None:
+            info.pid = pid
+        if pid and pid not in info.pids:
+            info.pids.append(pid)
+    return index