durable-workflow 2.2.0__tar.gz → 2.3.0__tar.gz

{durable_workflow-2.2.0/src/durable_workflow.egg-info → durable_workflow-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python client and worker SDK for Durable Workflow Cloud and self-hosted Server
 Author: Durable Workflow Contributors
 License-Expression: MIT

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "durable-workflow"
-version = "2.2.0"
+version = "2.3.0"
 description = "Python client and worker SDK for Durable Workflow Cloud and self-hosted Server"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -71,9 +71,9 @@ durable-workflow-replay-conformance = "durable_workflow.replay_conformance:main"
 durable-workflow-workflow-updates-conformance = "durable_workflow.workflow_updates_conformance:main"
 
 [tool.durable-workflow]
-product-train = "2.2.0"
-registry-version = "2.2.0"
-supported-server-versions = "2.4.0"
+product-train = "2.3.0"
+registry-version = "2.3.0"
+supported-server-versions = "2.4.2"
 worker-protocol-version = "1.19"
 control-plane-version = "2"
 durable-selection = true

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/src/durable_workflow/__init__.py

@@ -210,6 +210,7 @@ from .serializer import (
     to_avro_payload_values,
 )
 from .worker import Worker
+from .worker_session import WorkerSession, WorkerSessionOptions
 from .workflow import (
     ActivityRetryPolicy,
     ChildWorkflowRetryPolicy,
@@ -290,6 +291,8 @@ __all__ = [
     "TaskQueueQueryAdmission",
     "TaskQueueTaskAdmission",
     "Worker",
+    "WorkerSession",
+    "WorkerSessionOptions",
     "WorkerInterceptor",
     "WorkflowCommandResult",
     "WorkflowExecution",

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/src/durable_workflow/client.py

@@ -31,7 +31,7 @@ from collections.abc import AsyncIterator, Callable, Mapping, Sequence
 from dataclasses import dataclass
 from importlib.metadata import PackageNotFoundError
 from importlib.metadata import version as _pkg_version
-from typing import Any
+from typing import Any, cast
 from urllib.parse import quote, unquote, urlencode, urlsplit
 
 import httpx
@@ -61,6 +61,7 @@ from .external_storage import (
 from .metrics import CLIENT_REQUEST_DURATION_SECONDS, CLIENT_REQUESTS, NOOP_METRICS, MetricsRecorder
 from .nexus import NexusOperationResult, nexus_request_payload
 from .retry_policy import TransportRetryPolicy
+from .worker_session import WorkerSessionOptions
 
 PROTOCOL_VERSION = "1.19"
 CONTROL_PLANE_VERSION = "2"
@@ -71,9 +72,9 @@ PORTABLE_WORKER_AFFINITY_CAPABILITY_MANIFEST: dict[str, dict[str, str | bool]] =
         "implementation": "record_local_activity",
     },
     "worker_sessions": {
-        "supported": False,
+        "supported": True,
         "minimum_protocol_version": "1.18",
-        "reason": "python_worker_has_no_typed_session_lifecycle",
+        "implementation": "typed_worker_session",
     },
     "sticky_execution": {
         "supported": False,
@@ -4670,6 +4671,7 @@ class Client:
         supported_activity_types: list[str] | None = None,
         max_concurrent_workflow_tasks: int | None = None,
         max_concurrent_activity_tasks: int | None = None,
+        max_concurrent_worker_sessions: int | None = None,
         runtime: str = "python",
         sdk_version: str | None = None,
         build_id: str | None = None,
@@ -4693,6 +4695,8 @@ class Client:
             raise ValueError("max_concurrent_workflow_tasks must be at least 1")
         if max_concurrent_activity_tasks is not None and max_concurrent_activity_tasks < 1:
             raise ValueError("max_concurrent_activity_tasks must be at least 1")
+        if max_concurrent_worker_sessions is not None and max_concurrent_worker_sessions < 1:
+            raise ValueError("max_concurrent_worker_sessions must be at least 1")
         if (
             capabilities
             and _MESSAGE_STREAMS_CAPABILITY in capabilities
@@ -4721,6 +4725,8 @@ class Client:
             body["max_concurrent_workflow_tasks"] = max_concurrent_workflow_tasks
         if max_concurrent_activity_tasks is not None:
             body["max_concurrent_activity_tasks"] = max_concurrent_activity_tasks
+        if max_concurrent_worker_sessions is not None:
+            body["max_concurrent_worker_sessions"] = max_concurrent_worker_sessions
         if task_slots is not None:
             body["task_slots"] = task_slots
         if process_metrics is not None:
@@ -4729,6 +4735,32 @@ class Client:
             body["heartbeat_interval_seconds"] = heartbeat_interval_seconds
         return await self._request("POST", "/worker/register", worker=True, json=body)
 
+    async def create_worker_session(
+        self, worker_id: str, options: WorkerSessionOptions
+    ) -> dict[str, Any]:
+        return cast(dict[str, Any], await self._request(
+            "POST", "/worker/sessions", worker=True,
+            json={"worker_id": worker_id, **options.to_wire()},
+        ))
+
+    async def renew_worker_session(
+        self, worker_id: str, session_id: str, lease_seconds: int
+    ) -> dict[str, Any]:
+        if lease_seconds < 1:
+            raise ValueError("worker session lease_seconds must be positive")
+        return cast(dict[str, Any], await self._request(
+            "POST", f"/worker/sessions/{quote(session_id, safe='')}/heartbeat", worker=True,
+            json={"worker_id": worker_id, "lease_seconds": lease_seconds},
+        ))
+
+    async def close_worker_session(
+        self, worker_id: str, session_id: str, reason: str = "worker_shutdown"
+    ) -> dict[str, Any]:
+        return cast(dict[str, Any], await self._request(
+            "DELETE", f"/worker/sessions/{quote(session_id, safe='')}", worker=True,
+            json={"worker_id": worker_id, "reason": reason},
+        ))
+
     async def deregister_worker_registration(self, worker_id: str) -> dict[str, Any]:
         """Remove this runtime's successful worker-plane registration.
 

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/src/durable_workflow/worker.py

@@ -79,6 +79,7 @@ from .metrics import (
     MetricsRecorder,
 )
 from .retry_policy import _worker_storage_admission_stop
+from .worker_session import WorkerSession, WorkerSessionOptions
 from .workflow import (
     Command,
     FailWorkflow,
@@ -985,11 +986,13 @@ class Worker:
         task_queue: str,
         workflows: Iterable[type] = (),
         activities: Iterable[Callable[..., Any]] = (),
+        capabilities: Iterable[str] = (),
         worker_id: str | None = None,
         build_id: str | None = None,
         poll_timeout: float = 35.0,
         max_concurrent_workflow_tasks: int = 10,
         max_concurrent_activity_tasks: int = 10,
+        max_concurrent_worker_sessions: int = 10,
         shutdown_timeout: float = 30.0,
         heartbeat_interval: float = 60.0,
         metrics: MetricsRecorder | None = None,
@@ -1010,6 +1013,9 @@ class Worker:
             for workflow_type, workflow_cls in self.workflows.items()
         }
         self.activities = {_activity_name(a): a for a in activities}
+        self.capabilities = tuple(dict.fromkeys(capability.strip() for capability in capabilities))
+        if any(not capability for capability in self.capabilities):
+            raise ValueError("worker capabilities must be non-empty strings")
         self.worker_id = worker_id or f"py-worker-{uuid.uuid4().hex[:8]}"
         if build_id is not None:
             if not isinstance(build_id, str) or build_id.strip() == "":
@@ -1022,6 +1028,8 @@ class Worker:
             raise ValueError("max_concurrent_workflow_tasks must be at least 1")
         if max_concurrent_activity_tasks < 1:
             raise ValueError("max_concurrent_activity_tasks must be at least 1")
+        if max_concurrent_worker_sessions < 1:
+            raise ValueError("max_concurrent_worker_sessions must be at least 1")
         if heartbeat_interval <= 0:
             raise ValueError("heartbeat_interval must be positive")
 
@@ -1029,6 +1037,8 @@ class Worker:
         self._poll_http_timeout = poll_timeout
         self.max_concurrent_workflow_tasks = max_concurrent_workflow_tasks
         self.max_concurrent_activity_tasks = max_concurrent_activity_tasks
+        self.max_concurrent_worker_sessions = max_concurrent_worker_sessions
+        self._worker_sessions: dict[str, WorkerSession] = {}
         self._stop = asyncio.Event()
         self._wf_semaphore = asyncio.Semaphore(max_concurrent_workflow_tasks)
         self._act_semaphore = asyncio.Semaphore(max_concurrent_activity_tasks)
@@ -1192,6 +1202,9 @@ class Worker:
         if any(contract["updates"] for contract in self.workflow_command_contracts.values()):
             capabilities.append(WORKFLOW_UPDATES_CAPABILITY)
         capabilities.append(MESSAGE_STREAMS_CAPABILITY)
+        capabilities.extend(self.capabilities)
+        if PORTABLE_WORKER_AFFINITY_CAPABILITY_MANIFEST["worker_sessions"]["supported"]:
+            capabilities.append("worker_sessions")
 
         ack = await self.client.register_worker(
             worker_id=self.worker_id,
@@ -1202,6 +1215,7 @@ class Worker:
             supported_activity_types=list(self.activities),
             max_concurrent_workflow_tasks=self.max_concurrent_workflow_tasks,
             max_concurrent_activity_tasks=self.max_concurrent_activity_tasks,
+            max_concurrent_worker_sessions=self.max_concurrent_worker_sessions,
             build_id=self.build_id,
             capabilities=capabilities,
             capability_manifest=PORTABLE_WORKER_AFFINITY_CAPABILITY_MANIFEST,
@@ -1988,6 +2002,7 @@ class Worker:
             )
 
     async def _run_activity_task(self, task: dict[str, Any]) -> str:
+        self._track_worker_session_from_task(task)
         task_id: str = task["task_id"]
         attempt_id: str = task.get("activity_attempt_id") or task.get("attempt_id", "")
         activity_type: str = task.get("activity_type", "")
@@ -3025,6 +3040,10 @@ class Worker:
             "activity_available": max(
                 0, self.max_concurrent_activity_tasks - self._activity_inflight
             ),
+            "session_available": max(
+                0, self.max_concurrent_worker_sessions
+                - sum(session.active for session in self._worker_sessions.values())
+            ),
         }
 
     def _current_process_metrics(self) -> dict[str, Any]:
@@ -3263,6 +3282,30 @@ class Worker:
             raise RuntimeError("worker cannot run after stop() has been called")
         self._run_started = True
 
+    def worker_session(self, options: WorkerSessionOptions) -> WorkerSession:
+        """Return a typed lease handle held by this worker until shutdown."""
+        existing = self._worker_sessions.get(options.session_id)
+        if existing is not None:
+            if existing.options != options:
+                raise ValueError("worker session id already has different options")
+            return existing
+        session = WorkerSession(self.client, self.worker_id, options)
+        self._worker_sessions[options.session_id] = session
+        return session
+
+    def _track_worker_session_from_task(self, task: dict[str, Any]) -> None:
+        raw = task.get("worker_session")
+        if not isinstance(raw, dict) or not isinstance(raw.get("session_id"), str):
+            return
+        try:
+            options = WorkerSessionOptions.from_wire(raw)
+            session = self._worker_sessions.get(options.session_id)
+            if session is None:
+                session = self.worker_session(options)
+            session._track_leased_task()
+        except (ValueError, TypeError) as error:
+            log.warning("worker session metadata is invalid: %s", error)
+
     async def stop(self) -> None:
         """Stop polling, drain tasks, and remove the worker registration.
 
@@ -3321,6 +3364,17 @@ class Worker:
                 )
             await asyncio.gather(*in_flight, return_exceptions=True)
 
+        for session in self._worker_sessions.values():
+            if not session.active:
+                continue
+            try:
+                await asyncio.wait_for(
+                    session.close("worker_shutdown"),
+                    timeout=self._remaining_shutdown_time(deadline),
+                )
+            except Exception as error:
+                log.warning("worker session %s close failed: %s", session.options.session_id, error)
+
         if self._registered:
             await self.client.deregister_worker_registration(self.worker_id)
             self._registered = False

durable_workflow-2.3.0/src/durable_workflow/worker_session.py

@@ -0,0 +1,115 @@
+"""Typed worker-held session leases for activity routing."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+@dataclass(frozen=True)
+class WorkerSessionOptions:
+    session_id: str
+    queue: str | None = None
+    requirements: tuple[str, ...] = ()
+    lease_seconds: int = 120
+    ttl_seconds: int = 1800
+    max_concurrent_activities: int = 1
+    create_if_missing: bool = True
+    allow_reacquire_after_failure: bool = True
+
+    def __post_init__(self) -> None:
+        session_id = self.session_id.strip()
+        if not session_id:
+            raise ValueError("worker session id must be a non-empty string")
+        object.__setattr__(self, "session_id", session_id)
+        if self.queue is not None and not self.queue.strip():
+            raise ValueError("worker session queue must be a non-empty string when provided")
+        for name in ("lease_seconds", "ttl_seconds", "max_concurrent_activities"):
+            if getattr(self, name) < 1:
+                raise ValueError(f"worker session {name} must be positive")
+        requirements = tuple(dict.fromkeys(requirement.strip() for requirement in self.requirements))
+        if any(not requirement for requirement in requirements):
+            raise ValueError("worker session requirements must be non-empty strings")
+        object.__setattr__(self, "requirements", requirements)
+
+    def to_wire(self) -> dict[str, Any]:
+        wire: dict[str, Any] = {
+            "session_id": self.session_id,
+            "requirements": list(self.requirements),
+            "lease_seconds": self.lease_seconds,
+            "ttl_seconds": self.ttl_seconds,
+            "max_concurrent_activities": self.max_concurrent_activities,
+            "create_if_missing": self.create_if_missing,
+            "allow_reacquire_after_failure": self.allow_reacquire_after_failure,
+        }
+        if self.queue is not None:
+            wire["queue"] = self.queue
+        return wire
+
+    @classmethod
+    def from_wire(cls, wire: dict[str, Any]) -> WorkerSessionOptions:
+        return cls(
+            session_id=wire["session_id"],
+            queue=wire.get("queue"),
+            requirements=tuple(wire.get("requirements") or ()),
+            lease_seconds=wire.get("lease_seconds", 120),
+            ttl_seconds=wire.get("ttl_seconds", 1800),
+            max_concurrent_activities=wire.get("max_concurrent_activities", 1),
+            create_if_missing=wire.get("create_if_missing", True),
+            allow_reacquire_after_failure=wire.get("allow_reacquire_after_failure", True),
+        )
+
+
+class WorkerSession:
+    """A lease owned by one registered worker; state must be rebuilt after holder loss."""
+
+    def __init__(self, client: Client, worker_id: str, options: WorkerSessionOptions) -> None:
+        self.client = client
+        self.worker_id = worker_id
+        self.options = options
+        self._active = False
+        self._close_response: dict[str, Any] | None = None
+        self._lock = asyncio.Lock()
+
+    @property
+    def active(self) -> bool:
+        return self._active
+
+    async def create(self) -> dict[str, Any]:
+        async with self._lock:
+            response = await self.client.create_worker_session(self.worker_id, self.options)
+            self._active = True
+            self._close_response = None
+            return response
+
+    async def renew(self, lease_seconds: int | None = None) -> dict[str, Any]:
+        async with self._lock:
+            if not self._active:
+                raise RuntimeError("a closed or uncreated worker session cannot be renewed")
+            requested_lease = self.options.lease_seconds if lease_seconds is None else lease_seconds
+            return await self.client.renew_worker_session(
+                self.worker_id, self.options.session_id, requested_lease
+            )
+
+    async def close(self, reason: str = "worker_shutdown") -> dict[str, Any]:
+        async with self._lock:
+            if self._close_response is not None:
+                return self._close_response
+            response = await self.client.close_worker_session(self.worker_id, self.options.session_id, reason)
+            self._active = False
+            self._close_response = response
+            return response
+
+    def activity_options(self) -> dict[str, Any]:
+        return {"worker_session": self.options.to_wire()}
+
+    def rebuild_required_after_holder_loss(self) -> bool:
+        return True
+
+    def _track_leased_task(self) -> None:
+        self._active = True
+        self._close_response = None

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/src/durable_workflow/workflow.py

@@ -49,6 +49,7 @@ from .errors import (
 )
 from .external_storage import ExternalPayloadCache, ExternalStorageDriver
 from .nexus import NexusOperationResult, stable_nexus_idempotency_key
+from .worker_session import WorkerSessionOptions
 
 _WorkflowT = TypeVar("_WorkflowT")
 
@@ -467,6 +468,7 @@ class ScheduleActivity:
     schedule_to_start_timeout: int | None = None
     schedule_to_close_timeout: int | None = None
     heartbeat_timeout: int | None = None
+    worker_session: WorkerSessionOptions | None = None
     _parallel_group_path: list[dict[str, Any]] | None = field(
         default=None,
         init=False,
@@ -518,6 +520,8 @@ class ScheduleActivity:
             command["schedule_to_close_timeout"] = self.schedule_to_close_timeout
         if self.heartbeat_timeout is not None:
             command["heartbeat_timeout"] = self.heartbeat_timeout
+        if self.worker_session is not None:
+            command["worker_session"] = self.worker_session.to_wire()
         return command
 
     def _validate_timeouts(self) -> None:
@@ -1400,6 +1404,8 @@ def commands_to_server_commands(
                 server_command["schedule_to_close_timeout"] = command.schedule_to_close_timeout
             if command.heartbeat_timeout is not None:
                 server_command["heartbeat_timeout"] = command.heartbeat_timeout
+            if command.worker_session is not None:
+                server_command["worker_session"] = command.worker_session.to_wire()
             server_commands.append(server_command)
             continue
 
@@ -1831,6 +1837,7 @@ class WorkflowContext:
         schedule_to_start_timeout: int | None = None,
         schedule_to_close_timeout: int | None = None,
         heartbeat_timeout: int | None = None,
+        worker_session: WorkerSessionOptions | None = None,
     ) -> ScheduleActivity:
         return ScheduleActivity(
             activity_type=activity_type,
@@ -1841,6 +1848,7 @@ class WorkflowContext:
             schedule_to_start_timeout=schedule_to_start_timeout,
             schedule_to_close_timeout=schedule_to_close_timeout,
             heartbeat_timeout=heartbeat_timeout,
+            worker_session=worker_session,
         )
 
     def local_activity(

{durable_workflow-2.2.0 → durable_workflow-2.3.0/src/durable_workflow.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: durable-workflow
-Version: 2.2.0
+Version: 2.3.0
 Summary: Python client and worker SDK for Durable Workflow Cloud and self-hosted Server
 Author: Durable Workflow Contributors
 License-Expression: MIT

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/src/durable_workflow.egg-info/SOURCES.txt

@@ -24,6 +24,7 @@ src/durable_workflow/serializer.py
 src/durable_workflow/sync.py
 src/durable_workflow/testing.py
 src/durable_workflow/worker.py
+src/durable_workflow/worker_session.py
 src/durable_workflow/workflow.py
 src/durable_workflow/workflow_updates_conformance.py
 src/durable_workflow.egg-info/PKG-INFO
@@ -81,6 +82,7 @@ tests/test_update_signal_condition_replay.py
 tests/test_updates.py
 tests/test_wait_condition.py
 tests/test_worker.py
+tests/test_worker_session.py
 tests/test_workflow_result_timeout.py
 tests/test_workflow_streams.py
 tests/test_workflow_updates_conformance.py

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/tests/test_release_metadata.py

@@ -44,7 +44,7 @@ def test_worker_release_identity_matches_supported_server_and_protocol() -> None
     assert check_release_metadata.VERSION_PATTERN.fullmatch(project["version"]) is not None
     assert release["product-train"] == project["version"]
     assert release["registry-version"] == project["version"].replace("-rc.", "rc")
-    assert release["supported-server-versions"] == "2.4.0"
+    assert release["supported-server-versions"] == "2.4.2"
     assert release["worker-protocol-version"] == PROTOCOL_VERSION == "1.19"
     assert release["durable-selection"] is True
     assert release["durable-selection-minimum-worker-protocol-version"] == "1.19"

{durable_workflow-2.2.0 → durable_workflow-2.3.0}/tests/test_worker.py

@@ -422,6 +422,7 @@ class TestWorkerRegistration:
             "supported_activity_types": ["test-act"],
             "max_concurrent_workflow_tasks": 10,
             "max_concurrent_activity_tasks": 10,
+            "max_concurrent_worker_sessions": 10,
             "build_id": None,
             "capabilities": [
                 "memo_upserts",
@@ -430,6 +431,7 @@ class TestWorkerRegistration:
                 "local_activities",
                 "query_tasks",
                 MESSAGE_STREAMS_CAPABILITY,
+                "worker_sessions",
             ],
             "capability_manifest": {
                 "local_activities": {
@@ -438,9 +440,9 @@ class TestWorkerRegistration:
                     "implementation": "record_local_activity",
                 },
                 "worker_sessions": {
-                    "supported": False,
+                    "supported": True,
                     "minimum_protocol_version": "1.18",
-                    "reason": "python_worker_has_no_typed_session_lifecycle",
+                    "implementation": "typed_worker_session",
                 },
                 "sticky_execution": {
                     "supported": False,
@@ -451,6 +453,7 @@ class TestWorkerRegistration:
             "task_slots": {
                 "workflow_available": 10,
                 "activity_available": 10,
+                "session_available": 10,
             },
             "process_metrics": process_metrics,
         }
@@ -576,6 +579,7 @@ class TestWorkerRegistration:
             "query_tasks",
             WORKFLOW_UPDATES_CAPABILITY,
             MESSAGE_STREAMS_CAPABILITY,
+            "worker_sessions",
         ]
 
     @pytest.mark.asyncio
@@ -663,6 +667,7 @@ class TestWorkerRegistration:
             UPDATE_VALIDATION_TASKS_CAPABILITY,
             WORKFLOW_UPDATES_CAPABILITY,
             MESSAGE_STREAMS_CAPABILITY,
+            "worker_sessions",
         ]
 
     @pytest.mark.asyncio
@@ -762,6 +767,7 @@ class TestWorkerRegistration:
             DURABLE_SELECTION_CAPABILITY,
             "local_activities",
             MESSAGE_STREAMS_CAPABILITY,
+            "worker_sessions",
         ]
 
     @pytest.mark.asyncio

durable_workflow-2.3.0/tests/test_worker_session.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from durable_workflow import Client, Worker, WorkerSessionOptions
+from durable_workflow.workflow import ScheduleActivity, commands_to_server_commands
+
+
+def test_options_are_canonical_and_validate_bounds() -> None:
+    options = WorkerSessionOptions(
+        session_id="  render  ",
+        queue="gpu",
+        requirements=(" gpu:l4 ", "gpu:l4"),
+        max_concurrent_activities=2,
+    )
+    assert options.to_wire() == {
+        "session_id": "render",
+        "queue": "gpu",
+        "requirements": ["gpu:l4"],
+        "lease_seconds": 120,
+        "ttl_seconds": 1800,
+        "max_concurrent_activities": 2,
+        "create_if_missing": True,
+        "allow_reacquire_after_failure": True,
+    }
+    for invalid in ("", " \t"):
+        with pytest.raises(ValueError, match="session id"):
+            WorkerSessionOptions(invalid)
+    with pytest.raises(ValueError, match="positive"):
+        WorkerSessionOptions("render", lease_seconds=0)
+    with pytest.raises(ValueError, match="non-empty"):
+        WorkerSessionOptions("render", requirements=(" ",))
+
+
+def test_activity_command_carries_session_routing_in_both_encoding_paths() -> None:
+    options = WorkerSessionOptions("render", requirements=("gpu:l4",))
+    command = ScheduleActivity("render.frame", [{"frame": 1}], worker_session=options)
+    assert command.to_server_command("gpu")["worker_session"] == options.to_wire()
+    assert commands_to_server_commands([command], "gpu")[0]["worker_session"] == options.to_wire()
+
+
+@pytest.mark.asyncio
+async def test_client_session_verbs_use_worker_auth_and_canonical_paths() -> None:
+    client = Client("https://server.example", worker_token="worker-only", namespace="ns")
+    options = WorkerSessionOptions("render/one")
+    with patch.object(client, "_request", new_callable=AsyncMock, return_value={"outcome": "ok"}) as request:
+        await client.create_worker_session("worker-1", options)
+        await client.renew_worker_session("worker-1", options.session_id, 180)
+        await client.close_worker_session("worker-1", options.session_id, "shutdown")
+    assert request.await_count == 3
+    assert request.await_args_list[0].args == ("POST", "/worker/sessions")
+    assert request.await_args_list[0].kwargs == {
+        "worker": True, "json": {"worker_id": "worker-1", **options.to_wire()}
+    }
+    assert request.await_args_list[1].args == ("POST", "/worker/sessions/render%2Fone/heartbeat")
+    assert request.await_args_list[1].kwargs["json"]["lease_seconds"] == 180
+    assert request.await_args_list[2].args == ("DELETE", "/worker/sessions/render%2Fone")
+    assert request.await_args_list[2].kwargs["json"] == {"worker_id": "worker-1", "reason": "shutdown"}
+    with pytest.raises(ValueError, match="positive"):
+        await client.renew_worker_session("worker-1", "render", 0)
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_worker_session_lifecycle_and_shutdown_are_idempotent() -> None:
+    client = Client("https://server.example", worker_token="worker-only", namespace="ns")
+    worker = Worker(client, task_queue="gpu", worker_id="holder-1")
+    options = WorkerSessionOptions("render", queue="gpu")
+    session = worker.worker_session(options)
+    assert worker.worker_session(options) is session
+    assert worker._current_task_slots()["session_available"] == worker.max_concurrent_worker_sessions
+
+    with (
+        patch.object(client, "create_worker_session", new_callable=AsyncMock, return_value={"outcome": "created"}),
+        patch.object(
+            client, "renew_worker_session", new_callable=AsyncMock, return_value={"outcome": "renewed"}
+        ) as renew,
+        patch.object(
+            client, "close_worker_session", new_callable=AsyncMock, return_value={"outcome": "closed"}
+        ) as close,
+    ):
+        assert (await session.create())["outcome"] == "created"
+        assert worker._current_task_slots()["session_available"] == worker.max_concurrent_worker_sessions - 1
+        assert (await session.renew(180))["outcome"] == "renewed"
+        renew.assert_awaited_once_with("holder-1", "render", 180)
+        await worker.stop()
+        await worker.stop()
+        assert (await session.close())["outcome"] == "closed"
+        close.assert_awaited_once_with("holder-1", "render", "worker_shutdown")
+        assert worker._current_task_slots()["session_available"] == worker.max_concurrent_worker_sessions
+        with pytest.raises(RuntimeError, match="closed"):
+            await session.renew()
+
+    await client.aclose()
+
+
+@pytest.mark.asyncio
+async def test_claimed_session_is_tracked_and_closed_without_explicit_create() -> None:
+    client = Client("https://server.example", worker_token="worker-only", namespace="ns")
+    worker = Worker(client, task_queue="gpu", worker_id="replacement-holder")
+    worker._track_worker_session_from_task({
+        "worker_session": {
+            "session_id": "render",
+            "queue": "gpu",
+            "requirements": ["gpu:l4"],
+        }
+    })
+    session = worker.worker_session(WorkerSessionOptions("render", queue="gpu", requirements=("gpu:l4",)))
+    assert session.active
+    assert session.rebuild_required_after_holder_loss()
+    with patch.object(
+        client, "close_worker_session", new_callable=AsyncMock, return_value={"outcome": "closed"}
+    ) as close:
+        await worker.stop()
+    close.assert_awaited_once_with("replacement-holder", "render", "worker_shutdown")
+    await client.aclose()