worktree-controller 1.30.4__py3-none-any.whl

worktree_controller/native_session_recovery.py

@@ -0,0 +1,171 @@
+"""Narrow recovery of an archived Codex thread on a still-live shared daemon.
+
+The normal dead-process gate stays unchanged. This opt-in path observes the native
+server, never archives a thread, stops a process, or accepts caller-authored status.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import socket
+import stat
+import struct
+import time
+from dataclasses import asdict
+from pathlib import Path
+from typing import Any
+
+from .environment import runtime_authority_evidence
+from .models import ControllerError, WriterHolder
+from .writer_lease import holder_is_live
+
+CONTRACT = "archived-codex-binding-recovery/v1"
+_MAX_MESSAGE = 2_000_000
+
+
+def _blocked(reason: str) -> ControllerError:
+    return ControllerError("NATIVE_SESSION_RECOVERY_REFUSED", reason)
+
+
+def _shared_daemon(holder: WriterHolder) -> None:
+    if holder.client_id not in {"codex", "codex-cli"} or not holder.session_id:
+        raise _blocked("an exact Codex session identity is required")
+    if not holder_is_live(holder):
+        raise _blocked("use ordinary binding removal for an exited process")
+    proc = Path("/proc") / str(holder.pid)
+    arguments = (proc / "cmdline").read_bytes().split(b"\0")
+    if (
+        proc.stat().st_uid != os.getuid()
+        or b"app-server" not in arguments
+        or b"--managed-daemon" not in arguments
+    ):
+        raise _blocked("the holder is not the same user's managed shared Codex daemon")
+
+
+def _native_observation(holder: WriterHolder) -> dict[str, Any]:
+    # Lazy import keeps ordinary Controller observations usable without a transport.
+    from websockets.sync.client import unix_connect
+
+    path = Path.home() / ".codex/app-server-control/app-server-control.sock"
+    if path.lstat().st_uid != os.getuid():
+        raise _blocked("native control socket link authority is invalid")
+    # Codex's stable entry is a symlink to its private Unix socket. Pin the
+    # resolved endpoint, then verify the kernel peer against the recorded holder.
+    path = path.resolve(strict=True)
+    info = path.lstat()
+    if not stat.S_ISSOCK(info.st_mode) or info.st_uid != os.getuid():
+        raise _blocked("native control socket authority is invalid")
+    with unix_connect(
+        str(path), uri="ws://localhost/", open_timeout=5, close_timeout=1, max_size=_MAX_MESSAGE
+    ) as client:
+        pid, uid, _gid = struct.unpack(
+            "3i", client.socket.getsockopt(socket.SOL_SOCKET, socket.SO_PEERCRED, 12)
+        )
+        if pid != holder.pid or uid != os.getuid():
+            raise _blocked("native socket peer differs from the recorded holder")
+
+        def call(number: int, method: str, params: dict[str, Any]) -> dict[str, Any]:
+            client.send(json.dumps({"id": number, "method": method, "params": params}))
+            deadline = time.monotonic() + 5
+            for _ in range(100):
+                remaining = deadline - time.monotonic()
+                if remaining <= 0:
+                    raise _blocked("native observation timed out")
+                response = json.loads(client.recv(timeout=remaining))
+                if not isinstance(response, dict):
+                    raise _blocked("native response is not an object")
+                if response.get("id") == number:
+                    result = response.get("result")
+                    if not isinstance(result, dict) or "error" in response:
+                        raise _blocked("native observation was refused")
+                    return result
+            raise _blocked("native observation exceeded its notification bound")
+
+        call(
+            1,
+            "initialize",
+            {"clientInfo": {"name": "worktree_controller_recovery", "version": "1"}},
+        )
+        client.send(json.dumps({"method": "initialized", "params": {}}))
+        thread = call(2, "thread/read", {"threadId": holder.session_id, "includeTurns": False}).get(
+            "thread"
+        )
+        loaded = call(3, "thread/loaded/list", {}).get("data")
+        if not isinstance(thread, dict) or not isinstance(loaded, list):
+            raise _blocked("native thread observation is incomplete")
+        return {"thread": thread, "loaded": loaded, "peer_pid": pid}
+
+
+def _archived_thread(holder: WriterHolder, observation: dict[str, Any]) -> dict[str, Any]:
+    thread, loaded = observation["thread"], observation["loaded"]
+    if (
+        thread.get("id") != holder.session_id
+        or thread.get("status") != {"type": "notLoaded"}
+        or holder.session_id in loaded
+    ):
+        raise _blocked("the exact native thread must be unloaded")
+    archive = Path.home() / ".codex/archived_sessions"
+    raw_path = thread.get("path")
+    if not isinstance(raw_path, str):
+        raise _blocked("native archived rollout identity is missing")
+    path = Path(raw_path)
+    if not path.is_absolute() or not path.is_relative_to(archive):
+        raise _blocked("the exact native thread has not been archived")
+    if path.resolve(strict=True) != path or path.lstat().st_uid != os.getuid():
+        raise _blocked("native archived rollout authority is invalid")
+    if not stat.S_ISREG(path.lstat().st_mode):
+        raise _blocked("native archived rollout is not a regular file")
+    with path.open("rb") as stream:
+        first = stream.readline(262_145)
+    if len(first) > 262_144:
+        raise _blocked("native session metadata exceeds its bound")
+    record = json.loads(first)
+    if (
+        not isinstance(record, dict)
+        or record.get("type") != "session_meta"
+        or not isinstance(record.get("payload"), dict)
+        or record["payload"].get("id") != holder.session_id
+    ):
+        raise _blocked("native archived session metadata identity differs")
+    return {
+        "thread_id": holder.session_id,
+        "status": "notLoaded",
+        "archived_rollout": str(path),
+        "session_metadata_sha256": hashlib.sha256(first).hexdigest(),
+        "other_loaded_thread_count": len(loaded),
+        "peer_pid": observation["peer_pid"],
+    }
+
+
+def observe_archived_session(target: Path, holder: WriterHolder) -> dict[str, Any]:
+    """Prove a native terminal boundary and no remaining references to this checkout."""
+    try:
+        _shared_daemon(holder)
+        native = _archived_thread(holder, _native_observation(holder))
+        references = runtime_authority_evidence(target)
+        if any(
+            references[key]
+            for key in (
+                "managed_references",
+                "observed_references",
+                "managed_visibility_uncertainties",
+                "scan_uncertainties",
+            )
+        ):
+            raise _blocked("checkout use or uncertain runtime references remain")
+        _shared_daemon(holder)
+        return {
+            "contract": CONTRACT,
+            "holder": asdict(holder),
+            "native": native,
+            "runtime_authority": references,
+            "processes_stopped": 0,
+            "threads_archived": 0,
+        }
+    except ControllerError:
+        raise
+    except Exception as exc:
+        # No native response, rollout contents, connection details or credentials in errors.
+        raise _blocked(f"native recovery observation failed ({type(exc).__name__})") from None

worktree_controller/owner_actions.py

@@ -0,0 +1,34 @@
+"""Structured requests for the recorded task owner; never execution authority."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any
+
+CONTRACT = "checkout-owner-action/v1"
+
+
+def owner_action(repository_path: str, item: dict[str, Any], *, reason: str,
+                 required_actions: tuple[str, ...]) -> dict[str, Any]:
+    """Bind a continuation request to the exact allocation, owner, HEAD and CAS.
+
+    A Task consumer must match its existing binding and re-observe these facts
+    before restoring its owner. The request itself grants no writer or cleanup.
+    """
+    request = {
+        "contract": CONTRACT,
+        "repository_path": repository_path,
+        **{key: item.get(key) for key in
+           ("allocation_id", "task_key", "authority_key", "owner", "path", "branch", "head")},
+        "expected_record_version": item.get("record_version"),
+        "reason": reason,
+        "required_actions": list(required_actions),
+        "automatic_discard": False,
+        "execution_authority": False,
+    }
+    request["action_id"] = hashlib.sha256(
+        json.dumps(request, sort_keys=True, separators=(",", ":")).encode()
+    ).hexdigest()
+    request["inspect_argv"] = ["worktree-controller", "status", "--repo", repository_path, "--json"]
+    return request

worktree_controller/policy.py

@@ -0,0 +1,333 @@
+"""Load and validate repository worktree policy."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from .models import CANONICAL_ROLES, ControllerError, ConvergencePolicy, WorktreePolicy
+
+EXPECTED_TOP_LEVEL = {
+    "schema_version",
+    "limits",
+    "canonical",
+    "slots",
+    "review",
+    "authority",
+}
+EXPECTED_TOP_LEVEL_V2 = EXPECTED_TOP_LEVEL | {"publication"}
+EXPECTED_TOP_LEVEL_V3 = EXPECTED_TOP_LEVEL_V2 | {"release"}
+EXPECTED_TOP_LEVEL_V4 = EXPECTED_TOP_LEVEL_V3
+EXPECTED_TOP_LEVEL_V5 = EXPECTED_TOP_LEVEL_V4
+EXPECTED_TOP_LEVEL_V6 = EXPECTED_TOP_LEVEL_V5 | {"reconciler"}
+EXPECTED_TOP_LEVEL_V7 = EXPECTED_TOP_LEVEL_V6 | {"admission"}
+EXPECTED_TOP_LEVEL_V8 = EXPECTED_TOP_LEVEL_V7 | {"convergence"}
+CONVERGENCE_FIELDS = {
+    "enabled",
+    "grace_minutes",
+    "idle_hours_max",
+    "idle_hours_min",
+    "standing_reserve",
+}
+# Optional [convergence] switches; an absent switch keeps the conservative default.
+CONVERGENCE_OPTIONAL_FIELDS = {"release_unintegrated_handoffs"}
+
+
+def _table(data: dict[str, Any], name: str) -> dict[str, Any]:
+    value = data.get(name)
+    if not isinstance(value, dict):
+        raise ControllerError("INVALID_POLICY", f"policy table [{name}] is required")
+    return value
+
+
+def _positive_int(table: dict[str, Any], name: str) -> int:
+    value = table.get(name)
+    if not isinstance(value, int) or isinstance(value, bool) or value < 1:
+        raise ControllerError("INVALID_POLICY", f"policy {name} must be a positive integer")
+    return value
+
+
+def _nonempty_string(table: dict[str, Any], name: str) -> str:
+    value = table.get(name)
+    if not isinstance(value, str) or not value.strip() or "\x00" in value:
+        raise ControllerError("INVALID_POLICY", f"policy {name} must be a non-empty string")
+    return value.strip()
+
+
+def _boolean(table: dict[str, Any], name: str) -> bool:
+    value = table.get(name)
+    if not isinstance(value, bool):
+        raise ControllerError("INVALID_POLICY", f"policy {name} must be boolean")
+    return value
+
+
+def default_policy(canonical_path: Path) -> WorktreePolicy:
+    return WorktreePolicy(
+        path=canonical_path / ".agents" / "worktree-policy.toml",
+        present=False,
+        policy_schema_version=1,
+        normal_limit=5,
+        hard_limit=6,
+        canonical_protected=True,
+        canonical_allowed_roles=CANONICAL_ROLES,
+        integration_candidate_limit=1,
+        integration_prepare_limit=1,
+        feature_audit_slots=3,
+        emergency_slots=1,
+        recovery_reserve=0,
+        retained_slots=0,
+        reconciler_enabled=False,
+        reconciler_actor="lifecycle-reconciler",
+        reconciler_legacy_adoption=False,
+        main_publish_limit=1,
+        publication_remote="origin",
+        publication_branch="main",
+        automatic_feature_audit_release=False,
+        automatic_integration_continuation=False,
+        preserved_auto_release=False,
+        release_intent_ttl_seconds=3600,
+        stale_warning_days=7,
+        require_adoption=True,
+        require_task_key=True,
+        require_authority_key=True,
+        unique_active_feature_authority=True,
+    )
+
+
+def load_policy(canonical_path: Path) -> WorktreePolicy:
+    path = canonical_path / ".agents" / "worktree-policy.toml"
+    if not path.exists():
+        return default_policy(canonical_path)
+    if not path.is_file() or path.is_symlink():
+        raise ControllerError("INVALID_POLICY", f"policy is not a regular file: {path}")
+    try:
+        with path.open("rb") as handle:
+            data = tomllib.load(handle)
+    except (OSError, tomllib.TOMLDecodeError) as exc:
+        raise ControllerError("INVALID_POLICY", f"cannot read policy: {exc}") from exc
+    return parse_policy(canonical_path, data)
+
+
+def parse_policy(canonical_path: Path, data: dict[str, Any]) -> WorktreePolicy:
+    """Validate policy data read from the checkout or a pinned publication tree."""
+    path = canonical_path / ".agents" / "worktree-policy.toml"
+    schema_version = data.get("schema_version")
+    if schema_version == 1:
+        if set(data) != EXPECTED_TOP_LEVEL:
+            raise ControllerError("INVALID_POLICY", "policy schema v1 fields are invalid")
+    elif schema_version == 2:
+        if set(data) != EXPECTED_TOP_LEVEL_V2:
+            raise ControllerError("INVALID_POLICY", "policy schema v2 fields are invalid")
+    elif schema_version == 3:
+        if set(data) != EXPECTED_TOP_LEVEL_V3:
+            raise ControllerError("INVALID_POLICY", "policy schema v3 fields are invalid")
+    elif schema_version == 4:
+        if set(data) != EXPECTED_TOP_LEVEL_V4:
+            raise ControllerError("INVALID_POLICY", "policy schema v4 fields are invalid")
+    elif schema_version == 5:
+        if set(data) != EXPECTED_TOP_LEVEL_V5:
+            raise ControllerError("INVALID_POLICY", "policy schema v5 fields are invalid")
+    elif schema_version == 6:
+        if set(data) != EXPECTED_TOP_LEVEL_V6:
+            raise ControllerError("INVALID_POLICY", "policy schema v6 fields are invalid")
+    elif schema_version == 7:
+        if set(data) != EXPECTED_TOP_LEVEL_V7:
+            raise ControllerError("INVALID_POLICY", "policy schema v7 fields are invalid")
+    elif schema_version == 8:
+        if set(data) != EXPECTED_TOP_LEVEL_V8:
+            raise ControllerError("INVALID_POLICY", "policy schema v8 fields are invalid")
+    else:
+        raise ControllerError("INVALID_POLICY", "unsupported policy schema version")
+
+    limits = _table(data, "limits")
+    canonical = _table(data, "canonical")
+    slots = _table(data, "slots")
+    review = _table(data, "review")
+    authority = _table(data, "authority")
+    if set(limits) != {"normal_limit", "hard_limit"}:
+        raise ControllerError("INVALID_POLICY", "policy [limits] fields are invalid")
+    if set(canonical) != {"protected", "allowed_roles"}:
+        raise ControllerError("INVALID_POLICY", "policy [canonical] fields are invalid")
+    expected_slots = (
+        {"integration", "feature_or_audit", "emergency"}
+        if schema_version == 1
+        else {
+            ("integration_prepare_limit" if schema_version >= 4 else "integration_candidate_limit"),
+            "feature_or_audit",
+            "emergency",
+            "recovery_reserve",
+        }
+        | ({"retained"} if schema_version >= 5 else set())
+    )
+    if set(slots) != expected_slots:
+        raise ControllerError("INVALID_POLICY", "policy [slots] fields are invalid")
+    if set(review) != {"stale_warning_days"}:
+        raise ControllerError("INVALID_POLICY", "policy [review] fields are invalid")
+    if set(authority) != {
+        "require_adoption",
+        "require_task_key",
+        "require_authority_key",
+        "unique_active_feature_authority",
+    }:
+        raise ControllerError("INVALID_POLICY", "policy [authority] fields are invalid")
+
+    normal_limit = _positive_int(limits, "normal_limit")
+    hard_limit = _positive_int(limits, "hard_limit")
+    if normal_limit >= hard_limit:
+        raise ControllerError("INVALID_POLICY", "normal_limit must be below hard_limit")
+    allowed_roles = canonical.get("allowed_roles")
+    if (
+        not isinstance(allowed_roles, list)
+        or not allowed_roles
+        or not all(isinstance(item, str) and item for item in allowed_roles)
+    ):
+        raise ControllerError("INVALID_POLICY", "canonical allowed_roles must be a string list")
+    stale = _positive_int(review, "stale_warning_days")
+    integration = _positive_int(
+        slots,
+        (
+            "integration"
+            if schema_version == 1
+            else "integration_prepare_limit"
+            if schema_version >= 4
+            else "integration_candidate_limit"
+        ),
+    )
+    feature_audit = _positive_int(slots, "feature_or_audit")
+    emergency = _positive_int(slots, "emergency")
+    recovery = 0 if schema_version == 1 else _positive_int(slots, "recovery_reserve")
+    retained = _positive_int(slots, "retained") if schema_version >= 5 else 0
+
+    # Automatic reconciliation is delegated, never assumed: a repository that has
+    # not opted in keeps the pre-lease behaviour exactly, so installing a newer
+    # Controller before migrating a policy changes nothing.
+    reconciler_enabled = False
+    reconciler_actor = "lifecycle-reconciler"
+    reconciler_legacy_adoption = False
+    if schema_version >= 6:
+        reconciler = _table(data, "reconciler")
+        if set(reconciler) != {"enabled", "actor", "allow_legacy_adoption"}:
+            raise ControllerError("INVALID_POLICY", "policy [reconciler] fields are invalid")
+        reconciler_enabled = _boolean(reconciler, "enabled")
+        reconciler_actor = _nonempty_string(reconciler, "actor")
+        reconciler_legacy_adoption = _boolean(reconciler, "allow_legacy_adoption")
+    # Counts are independent observations under resource admission. Requiring
+    # their historical slot sums to balance would still turn them into a veto.
+
+    if schema_version == 1:
+        main_publish_limit = 1
+        publication_remote = "origin"
+        publication_branch = "main"
+    else:
+        publication = _table(data, "publication")
+        if set(publication) != {"main_publish_limit", "remote", "branch"}:
+            raise ControllerError("INVALID_POLICY", "policy [publication] fields are invalid")
+        main_publish_limit = _positive_int(publication, "main_publish_limit")
+        if main_publish_limit != 1:
+            raise ControllerError(
+                "INVALID_POLICY", "this controller version requires main_publish_limit = 1"
+            )
+        publication_remote = _nonempty_string(publication, "remote")
+        publication_branch = _nonempty_string(publication, "branch")
+
+    if schema_version < 3:
+        automatic_feature_audit_release = False
+        automatic_integration_continuation = False
+        preserved_auto_release = False
+        release_intent_ttl_seconds = 3600
+    else:
+        release_policy = _table(data, "release")
+        expected_release = {"automatic_feature_audit", "intent_ttl_seconds"}
+        if schema_version >= 4:
+            expected_release |= {
+                "automatic_integration_continuation",
+                "preserved_auto_release",
+            }
+        if set(release_policy) != expected_release:
+            raise ControllerError("INVALID_POLICY", "policy [release] fields are invalid")
+        automatic_feature_audit_release = _boolean(release_policy, "automatic_feature_audit")
+        automatic_integration_continuation = (
+            _boolean(release_policy, "automatic_integration_continuation")
+            if schema_version >= 4
+            else False
+        )
+        preserved_auto_release = (
+            _boolean(release_policy, "preserved_auto_release") if schema_version >= 4 else False
+        )
+        if preserved_auto_release:
+            raise ControllerError(
+                "INVALID_POLICY", "this controller version requires preserved_auto_release = false"
+            )
+        release_intent_ttl_seconds = _positive_int(release_policy, "intent_ttl_seconds")
+
+    growth_bytes, growth_inodes = 2 * 1024**3, 100_000
+    if schema_version >= 7:
+        admission = _table(data, "admission")
+        if set(admission) != {"strategy", "checkout_growth_bytes", "checkout_growth_inodes"} or admission.get("strategy") != "resource-budget-v1":
+            raise ControllerError("INVALID_POLICY", "unsupported resource admission policy")
+        growth_bytes = _positive_int(admission, "checkout_growth_bytes")
+        growth_inodes = _positive_int(admission, "checkout_growth_inodes")
+
+    convergence = None
+    if schema_version >= 8:
+        table = _table(data, "convergence")
+        if not CONVERGENCE_FIELDS <= set(table) <= CONVERGENCE_FIELDS | CONVERGENCE_OPTIONAL_FIELDS:
+            raise ControllerError("INVALID_POLICY", "policy [convergence] fields are invalid")
+        idle_max = _positive_int(table, "idle_hours_max")
+        idle_min = _positive_int(table, "idle_hours_min")
+        if idle_min > idle_max:
+            raise ControllerError(
+                "INVALID_POLICY", "policy idle_hours_min must not exceed idle_hours_max"
+            )
+        if not reconciler_enabled:
+            raise ControllerError(
+                "INVALID_POLICY", "retention convergence requires the delegated reconciler"
+            )
+        convergence = ConvergencePolicy(
+            enabled=_boolean(table, "enabled"),
+            grace_minutes=_positive_int(table, "grace_minutes"),
+            idle_hours_max=idle_max,
+            idle_hours_min=idle_min,
+            standing_reserve=_positive_int(table, "standing_reserve"),
+            release_unintegrated_handoffs=(
+                _boolean(table, "release_unintegrated_handoffs")
+                if "release_unintegrated_handoffs" in table
+                else False
+            ),
+        )
+
+    return WorktreePolicy(
+        path=path,
+        present=True,
+        policy_schema_version=schema_version,
+        normal_limit=normal_limit,
+        hard_limit=hard_limit,
+        canonical_protected=_boolean(canonical, "protected"),
+        canonical_allowed_roles=frozenset(allowed_roles),
+        integration_candidate_limit=integration,
+        integration_prepare_limit=integration,
+        feature_audit_slots=feature_audit,
+        emergency_slots=emergency,
+        recovery_reserve=recovery,
+        retained_slots=retained,
+        reconciler_enabled=reconciler_enabled,
+        reconciler_actor=reconciler_actor,
+        reconciler_legacy_adoption=reconciler_legacy_adoption,
+        main_publish_limit=main_publish_limit,
+        publication_remote=publication_remote,
+        publication_branch=publication_branch,
+        automatic_feature_audit_release=automatic_feature_audit_release,
+        automatic_integration_continuation=automatic_integration_continuation,
+        preserved_auto_release=preserved_auto_release,
+        release_intent_ttl_seconds=release_intent_ttl_seconds,
+        stale_warning_days=stale,
+        require_adoption=_boolean(authority, "require_adoption"),
+        require_task_key=_boolean(authority, "require_task_key"),
+        require_authority_key=_boolean(authority, "require_authority_key"),
+        unique_active_feature_authority=_boolean(authority, "unique_active_feature_authority"),
+        resource_admission=True,
+        checkout_growth_bytes=growth_bytes,
+        checkout_growth_inodes=growth_inodes,
+        convergence=convergence,
+    )