ccx-native 0.0.1 → 0.2.0

package/ccx/store/discovery.py

@@ -0,0 +1,170 @@
+"""Explicit full-UUID worker inventory discovery; never runtime addressing.
+
+The CLI resolves only selected user worker-reference fields before dispatch.
+Ordinary client, V1, native owner and store APIs remain exact-ID-only.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from ccx.errors import AmbiguousWorker, InvalidRequest, SessionUnavailable, worker_not_found
+from ccx.store.identity import (
+    ENGINES, EngineMismatch, IdentityError, UnknownWorker, canonical_worker_id,
+)
+from ccx.store.root import GenerationError, require_ccx_active
+
+_PREFIX = re.compile(r"[0-9a-f]{8}[0-9a-f-]{0,27}\Z", re.ASCII)
+
+
+def _query(value: str) -> tuple[str | None, str, bool]:
+    """(explicit engine, textual UUID query, is_incomplete_prefix)."""
+    if not isinstance(value, str) or not value:
+        raise InvalidRequest("worker query must be a nonempty canonical UUID or prefix")
+    if ":" in value:
+        engine, sep, uuid_text = value.partition(":")
+        if sep != ":" or engine not in ENGINES or ":" in uuid_text:
+            raise InvalidRequest("worker query must be bare or claude:/codex: qualified")
+    else:
+        engine, uuid_text = None, value
+    if len(uuid_text) == 36:
+        try:
+            canonical_worker_id(uuid_text)
+        except IdentityError as exc:
+            raise InvalidRequest(
+                "complete worker UUID must be canonical lowercase UUIDv4"
+            ) from exc
+        return engine, uuid_text, False
+    if not _PREFIX.fullmatch(uuid_text):
+        raise InvalidRequest(
+            "worker prefix must start with 8 lowercase hex characters, "
+            "continue with lowercase hex/hyphens, and be at most 35 characters; "
+            "no names, casefolding or compact-UUID aliases"
+        )
+    return engine, uuid_text, True
+
+
+def _candidates(store, engine: str | None, prefix: str) -> list[str]:
+    """Validated active workers whose full UUID starts with ``prefix``.
+
+    Only owner files whose NAME matches are read and validated, so a lookup
+    costs O(matches), not a validation of the whole fleet.
+    """
+    matches = []
+    try:
+        for worker_id in store.owner_ids(prefix=prefix):
+            try:
+                owner = store.resolve(f"{engine}:{worker_id}" if engine else worker_id)
+            except (UnknownWorker, EngineMismatch):
+                continue  # reserved/quarantined, or the other engine
+            matches.append(owner.worker)
+    except (GenerationError, IdentityError, OSError) as exc:
+        raise SessionUnavailable(f"managed worker inventory unavailable: {exc}") from exc
+    return sorted(matches)
+
+
+def _revalidate(store) -> None:
+    try:
+        store.revalidate()
+    except (GenerationError, OSError) as exc:
+        raise SessionUnavailable(f"managed worker generation changed: {exc}") from exc
+
+
+def _match(query: str, engine: str | None, prefix: str, store) -> str:
+    matches = _candidates(store, engine, prefix)
+    if not matches and engine is not None:
+        other = _candidates(store, None, prefix)
+        if len(other) == 1:
+            found, _, worker_id = other[0].partition(":")
+            raise InvalidRequest(f"{query} is a {found.capitalize()} worker; use "
+                                 f"{found}:{worker_id[:8]} or the bare prefix")
+    if not matches:
+        raise worker_not_found(query)
+    if len(matches) > 1:
+        raise AmbiguousWorker(query, matches)
+    return matches[0]
+
+
+def resolve_worker(query: str) -> str:
+    """Explicitly resolve a full UUID or unique textual prefix to engine:UUID.
+
+    This is a current read-only inventory query, NOT permission to pass the
+    prefix to ordinary Python methods, V1, host/daemon or persisted references.
+    """
+    from ccx import constants
+
+    engine, body, incomplete = _query(query)
+    try:
+        store = require_ccx_active(constants.CCX_ROOT)
+    except (GenerationError, OSError) as exc:
+        raise SessionUnavailable(f"ACTIVE managed worker inventory unavailable: {exc}") from exc
+    if not incomplete:
+        try:
+            owner = store.resolve(query)
+        except UnknownWorker as exc:
+            raise worker_not_found(query) from exc
+        except EngineMismatch as exc:
+            raise InvalidRequest(str(exc)) from exc
+        except (GenerationError, OSError) as exc:
+            raise SessionUnavailable(f"managed worker lookup unavailable: {exc}") from exc
+        resolved = owner.worker
+    else:
+        resolved = _match(query, engine, body, store)
+    _revalidate(store)
+    return resolved
+
+
+def resolve_cli_fields(namespace: Any, store, fields: tuple[str, ...], *,
+                       check_exact: bool = False) -> None:
+    """All-or-nothing namespace preflight; prefixes read only matching owners.
+
+    Complete exact UUIDs stay on the handler's fast path unless ``check_exact``
+    requests a missing-owner preflight. Multi-target report batches preserve
+    their existing per-row error behavior.
+    """
+    prepared: dict[str, list[tuple[str, str | None, str, bool]]] = {}
+    any_prefix = False
+    for field in fields:
+        value = getattr(namespace, field, None)
+        if value is None:
+            continue
+        values = value if isinstance(value, list) else [value]
+        parsed = []
+        for item in values:
+            engine, uuid_text, incomplete = _query(item)
+            parsed.append((item, engine, uuid_text, incomplete))
+            any_prefix = any_prefix or incomplete
+        prepared[field] = parsed
+    if check_exact:
+        for specs in prepared.values():
+            for original, _engine, _uuid_text, incomplete in specs:
+                if incomplete:
+                    continue
+                try:
+                    store.resolve(original)
+                except UnknownWorker as exc:
+                    if str(exc) == "full UUID is not present in global owner index":
+                        raise worker_not_found(original) from exc
+                    # Reserved/quarantined identities retain the verb's own
+                    # refusal; they are not missing global owner entries.
+                except EngineMismatch as exc:
+                    raise InvalidRequest(str(exc)) from exc
+                except (GenerationError, OSError):
+                    # Other refusal reasons retain the handler's existing type,
+                    # message and exit code rather than being normalized here.
+                    pass
+    if not any_prefix:
+        return
+
+    rewritten: dict[str, str | list[str]] = {}
+    for field, specs in prepared.items():
+        resolved = [
+            _match(original, engine, uuid_text, store) if incomplete else original
+            for original, engine, uuid_text, incomplete in specs
+        ]
+        rewritten[field] = (resolved if isinstance(getattr(namespace, field), list)
+                            else resolved[0])
+    _revalidate(store)
+    # Nothing from any field was applied until every prefix succeeded.
+    for field, resolved in rewritten.items():
+        setattr(namespace, field, resolved)

package/ccx/store/identity.py

@@ -0,0 +1,105 @@
+"""Exact CCX worker identity and engine-qualified target validation.
+
+Pure canonical UUID and owner contracts; no file I/O, provider discovery,
+environment lookup, or runtime compatibility aliases.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from uuid import UUID, uuid4
+
+IDENTITY_SCHEMA_VERSION = 2
+MANIFEST_SCHEMA_VERSION = 1
+ENGINES = frozenset({"claude", "codex"})
+OWNER_STATES = frozenset({"worker", "indeterminate-reserved", "quarantined"})
+
+
+class IdentityError(ValueError):
+    """Unusable or contradictory CCX-managed identity."""
+
+
+class InvalidTarget(IdentityError):
+    """Not a complete canonical managed UUID or qualified UUID."""
+
+
+class UnknownWorker(IdentityError):
+    """Canonical UUID has no CCX-owned record or is reserved."""
+
+
+class EngineMismatch(IdentityError):
+    """An explicit engine disagrees with the immutable CCX owner."""
+
+
+class OwnerConflict(IdentityError):
+    """One full UUID has two inconsistent owners/reservations."""
+
+
+def canonical_worker_id(value: str) -> str:
+    """Require lowercase, hyphenated RFC 4122 UUIDv4 (including variant)."""
+    if not isinstance(value, str):
+        raise InvalidTarget("worker id must be a canonical lowercase UUIDv4")
+    try:
+        value_uuid = UUID(value)
+    except (ValueError, TypeError, AttributeError) as exc:
+        raise InvalidTarget("worker id must be a canonical lowercase UUIDv4") from exc
+    if value_uuid.version != 4 or value_uuid.variant != "specified in RFC 4122" or str(value_uuid) != value:
+        raise InvalidTarget("worker id must be a canonical lowercase UUIDv4")
+    return value
+
+
+def mint_worker_id() -> str:
+    """Independently random UUIDv4; NEVER preserve or derive an old short."""
+    return str(uuid4())
+
+
+@dataclass(frozen=True)
+class ManagedTarget:
+    worker_id: str
+    qualified_engine: str | None = None
+
+    def __post_init__(self) -> None:
+        canonical_worker_id(self.worker_id)
+        if self.qualified_engine is not None and self.qualified_engine not in ENGINES:
+            raise InvalidTarget("unsupported managed engine")
+
+    def qualified(self, owner_engine: str) -> str:
+        if owner_engine not in ENGINES:
+            raise IdentityError("invalid CCX engine")
+        if self.qualified_engine is not None and self.qualified_engine != owner_engine:
+            raise EngineMismatch("managed target engine does not match CCX ownership")
+        return f"{owner_engine}:{self.worker_id}"
+
+
+def parse_managed_target(target: str) -> ManagedTarget:
+    """Only a canonical full UUID or engine:full UUID; never a display alias."""
+    if not isinstance(target, str):
+        raise InvalidTarget("managed target must be a canonical full worker UUID")
+    if ":" not in target:
+        return ManagedTarget(canonical_worker_id(target))
+    engine, separator, worker_id = target.partition(":")
+    if separator != ":" or engine not in ENGINES:
+        raise InvalidTarget("managed target must be a bare or engine-qualified full UUID")
+    return ManagedTarget(canonical_worker_id(worker_id), engine)
+
+
+@dataclass(frozen=True)
+class WorkerOwner:
+    worker_id: str
+    engine: str
+    state: str = "worker"
+
+    def __post_init__(self) -> None:
+        canonical_worker_id(self.worker_id)
+        if self.engine not in ENGINES:
+            raise IdentityError("unsupported CCX worker engine")
+        if self.state not in OWNER_STATES:
+            raise IdentityError("invalid CCX owner reservation state")
+
+    @property
+    def worker(self) -> str:
+        return f"{self.engine}:{self.worker_id}"
+
+    @property
+    def short(self) -> str:
+        """Nonunique display field, never a key for routing."""
+        return self.worker_id[:8]

package/ccx/store/journal_io.py

@@ -0,0 +1,79 @@
+"""Bounded reentrant locks and durable publication for Claude journals."""
+
+import contextlib
+import fcntl
+import json
+import os
+from pathlib import Path
+import tempfile
+import threading
+import time
+
+_LOCAL = threading.local()
+_THREAD_LOCKS: dict[Path, threading.RLock] = {}
+_THREAD_LOCKS_GUARD = threading.Lock()
+
+
+@contextlib.contextmanager
+def journal_lock(path: Path, *, timeout: float, busy_error: type[Exception], label: str):
+    # Key by lock path so different journals and roots cannot share ownership.
+    path = path.resolve()
+    held = getattr(_LOCAL, "held", None)
+    if held is None:
+        held = _LOCAL.held = set()
+    if path in held:
+        yield
+        return
+    budget = max(0.0, float(timeout))
+    deadline = time.monotonic() + budget
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with _THREAD_LOCKS_GUARD:
+        thread_lock = _THREAD_LOCKS.setdefault(path, threading.RLock())
+    acquired = (thread_lock.acquire(timeout=budget) if budget > 0
+                else thread_lock.acquire(blocking=False))
+    if not acquired:
+        raise busy_error(f"{label} is locked by this process (waited {budget:g}s)")
+    try:
+        fd = os.open(path, os.O_RDWR | os.O_CREAT, 0o600)
+        try:
+            while True:
+                try:
+                    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                    break
+                except OSError:
+                    if time.monotonic() >= deadline:
+                        raise busy_error(
+                            f"{label} is held by another process (waited {budget:g}s)"
+                        ) from None
+                    time.sleep(min(0.02, max(0.0, deadline - time.monotonic())))
+            held.add(path)
+            try:
+                yield
+            finally:
+                held.discard(path)
+        finally:
+            os.close(fd)
+    finally:
+        thread_lock.release()
+
+
+def write_json(path: Path, value: dict) -> None:
+    fd, tmp_name = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.", suffix=".tmp")
+    try:
+        with os.fdopen(fd, "w") as handle:
+            json.dump(value, handle, indent=2)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp_name, path)
+        # Persist the rename as well as the contents before acknowledging it.
+        dir_fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(dir_fd)
+        finally:
+            os.close(dir_fd)
+    except BaseException:
+        try:
+            os.unlink(tmp_name)
+        except FileNotFoundError:
+            pass
+        raise

package/ccx/store/liveness.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import json
+import pathlib
+from dataclasses import dataclass
+
+from ccx.system import oslayer
+from ccx.constants import CLAUDE_HOME
+
+def pid_alive(pid: int | None) -> bool:
+    if not pid:
+        return False
+    # Keep the historical EPERM-is-present projection, unlike controller runs.
+    return oslayer.probe_pid(pid) in ("exists", "denied")
+
+
+def owned_process(pid: int | None, start_token: str | int | None) -> oslayer.Presence:
+    """Compare an original PID/start identity with the current OS observation.
+
+    A PID without a start token cannot prove ownership; kernel-confirmed
+    absence still proves the original process is gone.
+    """
+    if not pid:
+        return "dead"
+    if not start_token:
+        return "dead" if oslayer.probe_pid(pid) == "missing" else "unprovable"
+    info = oslayer.process_info(pid)
+    if info.presence == "dead":
+        return "dead"
+    if info.presence != "alive" or info.start_token is None:
+        return "unprovable"
+    return "alive" if str(info.start_token) == str(start_token) else "dead"
+
+
+def owned_pid_alive(pid: int | None, start_token: str | int | None = None) -> bool:
+    """Is ``pid`` alive and still the process CCX recorded?
+
+    A PID can be reused after the original process exits, crashes or after a
+    reboot. A bare ``kill(pid, 0)`` can therefore report a stranger's process,
+    including another user's process (EPERM still means that PID exists).
+    Treating that as ownership could block a safe revive or signal a stranger.
+
+    Only the original PID plus its kernel start token proves a living owner.
+    Without the token, absence can be proven, but ownership cannot.
+    """
+    return owned_process(pid, start_token) == "alive"
+
+
+def lifecycle_host_alive(lifecycle: dict | None) -> bool:
+    """Whether a record's recorded managed host process is still that host."""
+    lifecycle = lifecycle or {}
+    return owned_pid_alive(lifecycle.get("hostPid"), lifecycle.get("hostStart"))
+
+
+def recorded_host_loaded(engine: str, lifecycle: dict | None) -> bool | None:
+    """RPC-free host presence, returning True/False only with identity proof.
+
+    Claude's recorded host PID/start identifies the original host as alive or
+    gone. Codex is served by the shared codexd: the daemon being alive says
+    nothing about whether this particular thread is loaded, so Codex returns
+    None (unobserved), not a fabricated True/False.
+    """
+    lifecycle = lifecycle if isinstance(lifecycle, dict) else {}
+    if engine != "claude" or not lifecycle.get("hostPid"):
+        return None
+    observed = owned_process(lifecycle.get("hostPid"), lifecycle.get("hostStart"))
+    return None if observed == "unprovable" else observed == "alive"
+
+
+def proc_argv(pid: int | None) -> list[str] | None:
+    """Full argv of a live pid from /proc/<pid>/cmdline, or None if unreadable.
+
+    Reads the whole cmdline — a Claude session-id passed via `--session-id`/
+    `--resume` sits well past the first argv tokens, so a truncated read would
+    miss it."""
+    raw = oslayer.read_argv(pid)
+    if raw is None:
+        return None
+    parts = [p.decode("utf-8", "replace") for p in raw.split(b"\x00") if p]
+    return parts or None
+
+
+def session_pid_alive(pid: int | None, session_id: str | None = None) -> bool:
+    """Is `pid` alive and actually the Claude session it claims to be?
+
+    `~/.claude/sessions/<pid>.json` is pid-keyed and accumulates stale files
+    (pids recycle). A bare `pid_alive` check could accept an unrelated process.
+    Accept either of these identity checks:
+
+      1. the live process's argv contains the 8-char session short — definitive,
+         and present whenever the session was launched with `--session-id` or
+         `--resume <id>` (bg agents, ccx-managed, resumed sessions); or
+      2. argv0 is the `claude` binary (plain `claude` interactive sessions don't
+         carry the id in argv). Claude rewrites its own pid-keyed session-meta on
+         startup, so a live claude at this pid means the meta is its own.
+
+    A recycled non-claude pid fails both gates, so its stale meta is rejected."""
+    if not pid_alive(pid):
+        return False
+    argv = proc_argv(pid)
+    if not argv:
+        return False
+    if session_id and session_id[:8] in " ".join(argv):
+        return True
+    argv0 = argv[0]
+    base = argv0.rsplit("/", 1)[-1].lower()
+    # `claude`, `~/.local/bin/claude`, or the SEA `.../claude/versions/<v>`.
+    return base == "claude" or "/claude/versions/" in argv0 or "/claude/launcher" in argv0
+
+
+@dataclass(frozen=True)
+class NativeClaudeState:
+    """One validated snapshot from Claude's pid-keyed interactive registry."""
+
+    pid: int
+    session_id: str
+    kind: str
+    status: str | None
+    status_updated_at: int | None
+    waiting_for: object | None
+    proc_start: str | int | None
+
+
+def proc_start_token(pid: int | None) -> str | None:
+    """Linux /proc start-time token for one live pid, or ``None``.
+
+    Field 22 is process start time in clock ticks since boot. It is stable for a
+    process lifetime and rejects a stale Claude pid-file after PID reuse.
+    """
+    return oslayer.process_info(pid).start_token
+
+
+def read_managed_claude_native_state(
+    pid: int | None,
+    session_id: str | None,
+    *,
+    claude_home: pathlib.Path | None = None,
+) -> NativeClaudeState | None:
+    """Read an exact managed Claude process's native session snapshot.
+
+    The registry is an upstream-internal compatibility surface, so this helper is
+    deliberately strict: any identity mismatch, unsupported kind, dead process,
+    stale process-start token, or unreadable JSON is simply ``None`` (no native
+    evidence). The caller must fall back to ordinary CCX semantic evidence.
+    """
+    if not pid or not session_id:
+        return None
+    root = claude_home or CLAUDE_HOME
+    try:
+        value = json.loads((root / "sessions" / f"{int(pid)}.json").read_text())
+    except (OSError, ValueError, TypeError):
+        return None
+    if not isinstance(value, dict):
+        return None
+    meta_pid = value.get("pid")
+    if meta_pid is not None:
+        try:
+            if int(meta_pid) != int(pid):
+                return None
+        except (TypeError, ValueError, OverflowError):
+            return None
+    if value.get("sessionId") != session_id:
+        return None
+    # Managed PTY workers are ordinary interactive Claude sessions. Future or
+    # missing kinds are not silently treated as equivalent.
+    kind = value.get("kind")
+    if kind != "interactive":
+        return None
+    meta_start = value.get("procStart")
+    if meta_start is None:
+        meta_start = value.get("procStartFt")
+    if meta_start is not None:
+        live_start = proc_start_token(pid)
+        if not oslayer.provider_start_matches(
+            meta_start, live_start, value.get("pidDomain")):
+            return None
+    elif not session_pid_alive(pid, session_id):
+        # Legacy local metadata may lack the provider token. It is not a
+        # Darwin authorization; only Linux's historical argv corroboration
+        # can supply the optional diagnostic snapshot.
+        return None
+    status = value.get("status")
+    status_updated_at = value.get("statusUpdatedAt")
+    if not isinstance(status_updated_at, int) or isinstance(status_updated_at, bool):
+        status_updated_at = None
+    return NativeClaudeState(
+        pid=int(pid),
+        session_id=session_id,
+        kind=kind,
+        status=status if isinstance(status, str) else None,
+        status_updated_at=status_updated_at,
+        waiting_for=value.get("waitingFor"),
+        proc_start=meta_start,
+    )