pz-cli 5.0.0__py3-none-any.whl

pz_core/runtime/worker/engine.py

@@ -0,0 +1,921 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, replace
+from datetime import UTC, datetime
+import inspect
+import json
+import os
+from pathlib import Path
+from time import perf_counter
+import secrets
+import signal
+from types import FrameType
+from typing import Any, Callable
+from uuid import uuid4
+
+from pz_core.runtime.adapters import RuntimeAdapter
+from pz_core.runtime.bindings import RuntimeBindings, compile_runtime_bindings
+from pz_core.runtime.errors import PzError, as_pz_error
+from pz_core.runtime.facades import HealthFacade
+from pz_core.runtime.lifecycle import (
+    LifecycleState,
+    activate_runtime_plan,
+    bind_runtime_plan,
+    shutdown_runtime_plan,
+)
+from pz_core.runtime.plan_context import active_runtime_plan
+from pz_core.runtime.plan import RuntimePlan, compile_runtime_plan
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerSession:
+    owner: str
+    worker_id: str
+    token: str
+    replica_slot: int
+    queue: str
+    kind: str
+    ttl_seconds: int
+    stale_seconds: int
+    max_wait_seconds: int
+    once: bool
+    concurrency: int
+    poll_interval_seconds: float
+    shutdown_timeout_seconds: float
+    workspace_dir: Path
+    lock_path: Path
+    pid_path: Path
+    heartbeat_path: Path
+    state_path: Path
+    temp_dir: Path
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerInvocation:
+    app_id: str | None
+    tool_name: str | None
+    replica_slot: int
+    once: bool
+    concurrency: int
+    poll_interval_seconds: float
+    shutdown_timeout_seconds: float
+
+
+@dataclass(slots=True)
+class WorkerControl:
+    shutdown_requested: bool = False
+    shutdown_signal: str | None = None
+    shutdown_signal_count: int = 0
+
+
+_WORKER_WORKSPACE_ENV = "PZ_WORKER_WORKSPACE_DIR"
+
+
+def _normalize_worker_argv(raw: object) -> list[str]:
+    if not isinstance(raw, list):
+        raise PzError(
+            code="PZ_WORKER_ARGV_INVALID",
+            message="Worker argv must be declared as a list of non-empty strings.",
+            stage="worker",
+            owner="runtime.worker",
+            action="dispatch_worker_cli",
+        )
+    normalized: list[str] = []
+    for index, item in enumerate(raw):
+        if not isinstance(item, str) or not item.strip():
+            raise PzError(
+                code="PZ_WORKER_ARGV_INVALID",
+                message=f"Worker argv[{index}] must be a non-empty string.",
+                stage="worker",
+                owner="runtime.worker",
+                action="dispatch_worker_cli",
+            )
+        normalized.append(item)
+    return normalized
+
+
+def _read_worker_bool(raw: object, *, field_name: str, default: bool) -> bool:
+    if raw is None:
+        return default
+    if not isinstance(raw, bool):
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be a boolean.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    return raw
+
+
+def _read_positive_int(raw: object, *, field_name: str, default: int) -> int:
+    if raw in (None, ""):
+        return default
+    if isinstance(raw, str):
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be an integer.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    if isinstance(raw, bool):
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be an integer.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    if isinstance(raw, float):
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be an integer.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    try:
+        value = int(raw)
+    except (TypeError, ValueError) as exc:
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be an integer.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        ) from exc
+    if value <= 0:
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be greater than zero.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    return value
+
+
+def _read_positive_float(raw: object, *, field_name: str, default: float) -> float:
+    if raw in (None, ""):
+        return default
+    if isinstance(raw, str):
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be a number.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    if isinstance(raw, bool):
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be a number.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    try:
+        value = float(raw)
+    except (TypeError, ValueError) as exc:
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be a number.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        ) from exc
+    if value <= 0:
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be greater than zero.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    return value
+
+
+def _read_worker_text(
+    raw: object,
+    *,
+    field_name: str,
+    default: str,
+) -> str:
+    if raw is None:
+        return default
+    if not isinstance(raw, str):
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be a string.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    value = raw.strip()
+    if not value:
+        raise PzError(
+            code=f"PZ_WORKER_{field_name.upper()}_INVALID",
+            message=f"worker.{field_name} must be a non-empty string.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+    return value
+
+
+def _compile_worker_session(
+    plan: RuntimePlan,
+    *,
+    app_id: str | None,
+    tool_name: str | None,
+    replica_slot: int | None,
+    once: bool,
+    concurrency: int | None,
+    poll_interval_seconds: float | None,
+    shutdown_timeout_seconds: float | None,
+) -> WorkerSession:
+    worker_settings = plan.settings.get("worker", default={})
+    if worker_settings in (None, {}):
+        worker_settings = {}
+    if not isinstance(worker_settings, dict):
+        raise PzError(
+            code="PZ_WORKER_SETTINGS_INVALID",
+            message="worker settings must be a table.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+
+    ttl_seconds = _read_positive_int(
+        worker_settings.get("ttl_seconds"),
+        field_name="ttl_seconds",
+        default=300,
+    )
+    stale_seconds = _read_positive_int(
+        worker_settings.get("stale_seconds"),
+        field_name="stale_seconds",
+        default=600,
+    )
+    max_wait_seconds = _read_positive_int(
+        worker_settings.get("max_wait_seconds"),
+        field_name="max_wait_seconds",
+        default=30,
+    )
+    concurrency_value = _read_positive_int(
+        concurrency if concurrency is not None else worker_settings.get("concurrency"),
+        field_name="concurrency",
+        default=1,
+    )
+    poll_interval_value = _read_positive_float(
+        (
+            poll_interval_seconds
+            if poll_interval_seconds is not None
+            else worker_settings.get("poll_interval_seconds", worker_settings.get("poll_interval"))
+        ),
+        field_name="poll_interval_seconds",
+        default=1.0,
+    )
+    shutdown_timeout_value = _read_positive_float(
+        (
+            shutdown_timeout_seconds
+            if shutdown_timeout_seconds is not None
+            else worker_settings.get(
+                "shutdown_timeout_seconds",
+                worker_settings.get("shutdown_timeout"),
+            )
+        ),
+        field_name="shutdown_timeout_seconds",
+        default=30.0,
+    )
+    if stale_seconds < ttl_seconds:
+        raise PzError(
+            code="PZ_WORKER_STALE_SECONDS_INVALID",
+            message="worker.stale_seconds must be greater than or equal to worker.ttl_seconds.",
+            stage="worker",
+            owner="runtime.worker",
+            action="create_worker_runtime",
+        )
+
+    owner = (
+        _read_worker_text(app_id, field_name="owner", default="pz")
+        if app_id is not None
+        else _read_worker_text(worker_settings.get("owner"), field_name="owner", default="pz")
+    )
+    tool = (
+        _read_worker_text(tool_name, field_name="tool_name", default="worker")
+        if tool_name is not None
+        else _read_worker_text(worker_settings.get("tool_name"), field_name="tool_name", default="worker")
+    )
+    replica_slot_value = _read_positive_int(
+        replica_slot,
+        field_name="replica_slot",
+        default=1,
+    )
+    queue = _read_worker_text(worker_settings.get("queue"), field_name="queue", default=tool)
+    kind = _read_worker_text(worker_settings.get("kind"), field_name="kind", default="default")
+
+    scope_dir_env = str(os.environ.get(_WORKER_WORKSPACE_ENV, "") or "").strip()
+    if scope_dir_env:
+        scope_dir = Path(scope_dir_env).expanduser()
+        if not scope_dir.is_absolute():
+            scope_dir = (plan.project.project_dir / scope_dir).resolve()
+    else:
+        scope_dir = plan.project.runtime_dir / "workers" / owner / tool
+        if replica_slot_value > 1:
+            scope_dir = scope_dir / "replicas" / str(replica_slot_value)
+    worker_id_suffix = f"r{replica_slot_value}-{uuid4().hex[:12]}"
+    worker_id = f"{owner}-{tool}-{worker_id_suffix}"
+    once_value = _read_worker_bool(once, field_name="once", default=False)
+
+    return WorkerSession(
+        owner=owner,
+        worker_id=worker_id,
+        token=secrets.token_urlsafe(24),
+        replica_slot=replica_slot_value,
+        queue=queue,
+        kind=kind,
+        ttl_seconds=ttl_seconds,
+        stale_seconds=stale_seconds,
+        max_wait_seconds=max_wait_seconds,
+        once=once_value,
+        concurrency=concurrency_value,
+        poll_interval_seconds=poll_interval_value,
+        shutdown_timeout_seconds=shutdown_timeout_value,
+        workspace_dir=scope_dir,
+        lock_path=scope_dir / "worker.lock",
+        pid_path=scope_dir / "worker.pid",
+        heartbeat_path=scope_dir / "heartbeat.json",
+        state_path=scope_dir / "state.json",
+        temp_dir=scope_dir / "tmp",
+    )
+
+
+def _ensure_lock_available(session: WorkerSession) -> None:
+    if not session.lock_path.exists():
+        return
+    raw = session.lock_path.read_text(encoding="utf-8").strip()
+    current_holder = raw
+    if raw.startswith("{"):
+        try:
+            payload = json.loads(raw)
+        except json.JSONDecodeError:
+            payload = None
+        if isinstance(payload, dict):
+            worker_id = payload.get("worker_id")
+            if worker_id is None:
+                current_holder = raw
+            elif isinstance(worker_id, str) and worker_id.strip():
+                current_holder = worker_id
+            else:
+                raise PzError(
+                    code="PZ_WORKER_LOCK_FILE_INVALID",
+                    message=(
+                        f"Worker lock file '{session.lock_path}' must declare worker_id "
+                        "as a non-empty string."
+                    ),
+                    stage="worker",
+                    owner=session.owner,
+                    action="activate_worker_runtime",
+                )
+    if not current_holder or current_holder == session.worker_id:
+        return
+    existing_pid = _read_runtime_pid(session)
+    if existing_pid is not None and not _pid_is_alive(existing_pid):
+        _reclaim_stale_runtime(session, current_holder=current_holder)
+        return
+    raise PzError(
+        code="PZ_WORKER_LOCK_CONFLICT",
+        message=(
+            f"Worker runtime already holds lock for '{session.owner}/{session.kind}' at "
+            f"'{session.lock_path}': {current_holder}"
+        ),
+        stage="worker",
+        owner=session.owner,
+        action="activate_worker_runtime",
+    )
+
+
+def _lock_payload(session: WorkerSession) -> dict[str, Any]:
+    return {
+        "owner": session.owner,
+        "worker_id": session.worker_id,
+        "token": session.token,
+        "replica_slot": session.replica_slot,
+        "queue": session.queue,
+        "kind": session.kind,
+        "ttl_seconds": session.ttl_seconds,
+        "stale_seconds": session.stale_seconds,
+        "max_wait_seconds": session.max_wait_seconds,
+        "once": session.once,
+        "concurrency": session.concurrency,
+        "poll_interval_seconds": session.poll_interval_seconds,
+        "shutdown_timeout_seconds": session.shutdown_timeout_seconds,
+        "acquired_at": datetime.now(UTC).isoformat(),
+    }
+
+
+def _read_runtime_pid(session: WorkerSession) -> int | None:
+    pid_sources: list[object] = []
+    if session.heartbeat_path.exists():
+        try:
+            payload = json.loads(session.heartbeat_path.read_text(encoding="utf-8"))
+        except Exception:
+            payload = None
+        if isinstance(payload, dict):
+            pid_sources.append(payload.get("pid"))
+    if session.pid_path.exists():
+        pid_sources.append(session.pid_path.read_text(encoding="utf-8").strip())
+    for raw in pid_sources:
+        try:
+            pid = int(raw)
+        except (TypeError, ValueError):
+            continue
+        if pid > 0:
+            return pid
+    return None
+
+
+def _pid_is_alive(pid: int | None) -> bool:
+    if pid is None:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    return True
+
+
+def _reclaim_stale_runtime(session: WorkerSession, *, current_holder: str) -> None:
+    worker_id = current_holder.strip()
+    token = ""
+    if session.heartbeat_path.exists():
+        try:
+            heartbeat = json.loads(session.heartbeat_path.read_text(encoding="utf-8"))
+        except Exception:
+            heartbeat = None
+        if isinstance(heartbeat, dict):
+            worker_id = str(heartbeat.get("worker_id") or worker_id).strip() or worker_id
+            token = str(heartbeat.get("token") or "").strip()
+    if session.lock_path.exists():
+        session.lock_path.unlink()
+    if session.pid_path.exists():
+        session.pid_path.unlink()
+    session.workspace_dir.mkdir(parents=True, exist_ok=True)
+    session.state_path.write_text(
+        json.dumps(
+            {
+                "owner": session.owner,
+                "worker_id": worker_id,
+                "token": token,
+                "replica_slot": session.replica_slot,
+                "queue": session.queue,
+                "kind": session.kind,
+                "ttl_seconds": session.ttl_seconds,
+                "stale_seconds": session.stale_seconds,
+                "max_wait_seconds": session.max_wait_seconds,
+                "once": session.once,
+                "concurrency": session.concurrency,
+                "poll_interval_seconds": session.poll_interval_seconds,
+                "shutdown_timeout_seconds": session.shutdown_timeout_seconds,
+                "phase": "stopped",
+                "reason": "stale_lock_reclaimed",
+            },
+            sort_keys=True,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    session.heartbeat_path.write_text(
+        json.dumps(
+            {
+                "owner": session.owner,
+                "worker_id": worker_id,
+                "token": token,
+                "replica_slot": session.replica_slot,
+                "phase": "stopped",
+                "timestamp": datetime.now(UTC).isoformat(),
+            },
+            sort_keys=True,
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class WorkerRuntime:
+    adapter: RuntimeAdapter
+    session: WorkerSession
+    app_id: str | None = None
+    tool_name: str | None = None
+    control: WorkerControl | None = None
+
+    @property
+    def plan(self) -> RuntimePlan:
+        return self.adapter.plan
+
+    @property
+    def state(self) -> LifecycleState:
+        return self.adapter.state
+
+    @property
+    def bindings(self) -> RuntimeBindings:
+        return self.adapter.bindings
+
+    @property
+    def invocation(self) -> WorkerInvocation:
+        return WorkerInvocation(
+            app_id=self.app_id,
+            tool_name=self.tool_name,
+            replica_slot=self.session.replica_slot,
+            once=self.session.once,
+            concurrency=self.session.concurrency,
+            poll_interval_seconds=self.session.poll_interval_seconds,
+            shutdown_timeout_seconds=self.session.shutdown_timeout_seconds,
+        )
+
+    def should_stop(self) -> bool:
+        return bool(self.control and self.control.shutdown_requested)
+
+    @property
+    def shutdown_signal(self) -> str | None:
+        if self.control is None:
+            return None
+        return self.control.shutdown_signal
+
+    @property
+    def shutdown_signal_count(self) -> int:
+        if self.control is None:
+            return 0
+        return self.control.shutdown_signal_count
+
+    def snapshot(self) -> dict[str, Any]:
+        payload = asdict(self.session)
+        payload["workspace_dir"] = str(self.session.workspace_dir)
+        payload["lock_path"] = str(self.session.lock_path)
+        payload["pid_path"] = str(self.session.pid_path)
+        payload["heartbeat_path"] = str(self.session.heartbeat_path)
+        payload["state_path"] = str(self.session.state_path)
+        payload["temp_dir"] = str(self.session.temp_dir)
+        payload["project_dir"] = str(self.plan.project.project_dir)
+        payload["phase"] = self.state.phase
+        payload["shutdown_requested"] = self.should_stop()
+        payload["shutdown_signal"] = self.shutdown_signal
+        payload["shutdown_signal_count"] = self.shutdown_signal_count
+        return payload
+
+    def request_shutdown(self, *, signal_name: str) -> None:
+        if self.control is None:
+            return
+        self.control.shutdown_requested = True
+        self.control.shutdown_signal = signal_name
+        self.control.shutdown_signal_count += 1
+        self.write_status("stopping", reason=f"signal:{signal_name}")
+        self.touch_heartbeat(phase="stopping")
+
+    def touch_heartbeat(self, *, phase: str) -> None:
+        payload = {
+            "owner": self.session.owner,
+            "worker_id": self.session.worker_id,
+            "token": self.session.token,
+            "replica_slot": self.session.replica_slot,
+            "phase": phase,
+            "pid": os.getpid(),
+            "timestamp": datetime.now(UTC).isoformat(),
+        }
+        self.session.heartbeat_path.write_text(
+            json.dumps(payload, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    def write_status(self, phase: str, *, reason: str | None = None) -> None:
+        payload = {
+            "owner": self.session.owner,
+            "worker_id": self.session.worker_id,
+            "token": self.session.token,
+            "replica_slot": self.session.replica_slot,
+            "queue": self.session.queue,
+            "kind": self.session.kind,
+            "ttl_seconds": self.session.ttl_seconds,
+            "stale_seconds": self.session.stale_seconds,
+            "max_wait_seconds": self.session.max_wait_seconds,
+            "once": self.session.once,
+            "concurrency": self.session.concurrency,
+            "poll_interval_seconds": self.session.poll_interval_seconds,
+            "shutdown_timeout_seconds": self.session.shutdown_timeout_seconds,
+            "phase": phase,
+        }
+        if reason:
+            payload["reason"] = reason
+        self.session.workspace_dir.mkdir(parents=True, exist_ok=True)
+        self.session.state_path.write_text(
+            json.dumps(payload, sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+
+    def activate(self) -> "WorkerRuntime":
+        if self.state.phase == "started":
+            return self
+        self.session.workspace_dir.mkdir(parents=True, exist_ok=True)
+        self.session.temp_dir.mkdir(parents=True, exist_ok=True)
+        _ensure_lock_available(self.session)
+        self.session.lock_path.write_text(
+            json.dumps(_lock_payload(self.session), sort_keys=True) + "\n",
+            encoding="utf-8",
+        )
+        self.session.pid_path.write_text(f"{os.getpid()}\n", encoding="utf-8")
+        self.write_status("starting")
+        self.touch_heartbeat(phase="starting")
+        try:
+            started_state = activate_runtime_plan(
+                self.plan,
+                self.state,
+                bindings=self.bindings,
+                host=None,
+            )
+        except Exception as exc:
+            if self.session.lock_path.exists():
+                self.session.lock_path.unlink()
+            if self.session.pid_path.exists():
+                self.session.pid_path.unlink()
+            self.write_status("stopped", reason=f"error:{exc.__class__.__name__}")
+            self.touch_heartbeat(phase="stopped")
+            raise
+        bindings = replace(
+            self.bindings,
+            health=HealthFacade(
+                self.plan,
+                started_state,
+                providers=self.bindings.providers,
+            ),
+        )
+        runtime = replace(
+            self,
+            adapter=replace(
+                self.adapter,
+                state=started_state,
+                bindings=bindings,
+            ),
+        )
+        runtime.write_status("started")
+        runtime.touch_heartbeat(phase="started")
+        return runtime
+
+    def shutdown(self, *, reason: str | None = None) -> "WorkerRuntime":
+        if self.state.phase == "stopped":
+            return self
+        self.write_status("stopping", reason=reason)
+        self.touch_heartbeat(phase="stopping")
+        started_at = perf_counter()
+        stopped = shutdown_runtime_plan(
+            self.plan,
+            self.state,
+            bindings=self.bindings,
+            host=None,
+        )
+        elapsed = perf_counter() - started_at
+        bindings = replace(
+            self.bindings,
+            health=HealthFacade(
+                self.plan,
+                stopped,
+                providers=self.bindings.providers,
+            ),
+        )
+        if self.session.lock_path.exists():
+            self.session.lock_path.unlink()
+        if self.session.pid_path.exists():
+            self.session.pid_path.unlink()
+        runtime = replace(self, adapter=replace(self.adapter, state=stopped, bindings=bindings))
+        timeout_reason = reason
+        if elapsed > self.session.shutdown_timeout_seconds:
+            timeout_reason = (
+                f"timeout:{elapsed:.3f}s>{self.session.shutdown_timeout_seconds:.3f}s"
+            )
+        runtime.write_status("stopped", reason=timeout_reason)
+        runtime.touch_heartbeat(phase="stopped")
+        if elapsed > self.session.shutdown_timeout_seconds:
+            raise PzError(
+                code="PZ_WORKER_SHUTDOWN_TIMEOUT_EXCEEDED",
+                message=(
+                    "Worker shutdown exceeded configured timeout: "
+                    f"{elapsed:.3f}s > {self.session.shutdown_timeout_seconds:.3f}s."
+                ),
+                stage="worker",
+                owner=self.app_id or self.session.owner,
+                action="shutdown_worker_runtime",
+            )
+        return runtime
+
+
+def _invoke_worker_entry(
+    entry: Callable[..., object],
+    *,
+    argv: list[str],
+    runtime: WorkerRuntime,
+) -> int:
+    signature = inspect.signature(entry)
+    kwargs: dict[str, object] = {}
+    if "runtime" in signature.parameters:
+        kwargs["runtime"] = runtime
+    if "worker" in signature.parameters:
+        kwargs["worker"] = runtime
+    if "session" in signature.parameters:
+        kwargs["session"] = runtime.session
+    if "bindings" in signature.parameters:
+        kwargs["bindings"] = runtime.bindings
+    if "plan" in signature.parameters:
+        kwargs["plan"] = runtime.plan
+    if "project_dir" in signature.parameters:
+        kwargs["project_dir"] = str(runtime.plan.project.project_dir)
+    if "once" in signature.parameters:
+        kwargs["once"] = runtime.session.once
+    if "concurrency" in signature.parameters:
+        kwargs["concurrency"] = runtime.session.concurrency
+    if "poll_interval" in signature.parameters:
+        kwargs["poll_interval"] = runtime.session.poll_interval_seconds
+    if "shutdown_timeout" in signature.parameters:
+        kwargs["shutdown_timeout"] = runtime.session.shutdown_timeout_seconds
+    if "control" in signature.parameters:
+        kwargs["control"] = runtime.control
+    if "should_stop" in signature.parameters:
+        kwargs["should_stop"] = runtime.should_stop
+    if "shutdown_requested" in signature.parameters:
+        kwargs["shutdown_requested"] = runtime.should_stop
+    with active_runtime_plan(runtime.plan):
+        result = entry(argv, **kwargs)
+        if inspect.isawaitable(result):
+            import asyncio
+
+            result = asyncio.run(result)
+    if isinstance(result, int):
+        return result
+    return 0
+
+
+def build_worker_status(runtime: WorkerRuntime) -> dict[str, Any]:
+    return {
+        "status": "ok",
+        "code": "PZ_WORKER_STATUS_OK",
+        "stage": "worker",
+        "owner": runtime.app_id or runtime.session.owner,
+        "action": "status",
+        "app_id": runtime.app_id,
+        "tool_name": runtime.tool_name,
+        "project_dir": str(runtime.plan.project.project_dir),
+        "phase": runtime.state.phase,
+        "session": runtime.snapshot(),
+        "liveness": asdict(runtime.bindings.health.liveness()),
+        "readiness": asdict(runtime.bindings.health.readiness()),
+    }
+
+
+def run_worker_entry(
+    entry: Callable[..., object],
+    *,
+    argv: list[str],
+    project_dir: str | Path | None = None,
+    installed_apps: tuple[str, ...] | None = None,
+    app_id: str | None = None,
+    tool_name: str | None = None,
+    replica_slot: int | None = None,
+    once: bool = False,
+    concurrency: int | None = None,
+    poll_interval_seconds: float | None = None,
+    shutdown_timeout_seconds: float | None = None,
+) -> int:
+    from pz_core.runtime.settings import active_settings_project
+
+    argv = _normalize_worker_argv(argv)
+    runtime = create_worker_runtime(
+        project_dir=project_dir,
+        installed_apps=installed_apps,
+        app_id=app_id,
+        tool_name=tool_name,
+        replica_slot=replica_slot,
+        once=once,
+        concurrency=concurrency,
+        poll_interval_seconds=poll_interval_seconds,
+        shutdown_timeout_seconds=shutdown_timeout_seconds,
+    )
+    started = runtime.activate()
+    previous_handlers: dict[int, Any] = {}
+    shutdown_reason: str | None = None
+    result_code: int | None = None
+    primary_error: PzError | None = None
+    primary_cause: Exception | None = None
+
+    def _handle_signal(signum: int, _frame: FrameType | None) -> None:
+        signal_name = signal.Signals(signum).name
+        started.request_shutdown(signal_name=signal_name)
+        if started.shutdown_signal_count >= 2:
+            raise KeyboardInterrupt(signal_name)
+
+    for signum in (signal.SIGINT, signal.SIGTERM):
+        try:
+            previous_handlers[signum] = signal.getsignal(signum)
+            signal.signal(signum, _handle_signal)
+        except (ValueError, OSError):
+            continue
+    try:
+        with active_settings_project(str(started.plan.project.project_dir)):
+            result_code = _invoke_worker_entry(entry, argv=argv, runtime=started)
+        if started.shutdown_signal:
+            shutdown_reason = f"signal:{started.shutdown_signal}"
+    except KeyboardInterrupt as exc:
+        shutdown_reason = f"signal:{exc}"
+        primary_cause = exc
+        primary_error = PzError(
+            code="PZ_WORKER_INTERRUPTED",
+            message=f"Worker interrupted by signal: {exc}",
+            stage="worker",
+            owner=app_id or "runtime.worker",
+            action="dispatch_worker_cli",
+            detail=str(exc) or exc.__class__.__name__,
+        )
+    except Exception as exc:
+        shutdown_reason = f"error:{exc.__class__.__name__}"
+        primary_cause = exc
+        primary_error = PzError(
+            code="PZ_WORKER_RUN_FAILED",
+            message=str(exc) or exc.__class__.__name__,
+            stage="worker",
+            owner=app_id or "runtime.worker",
+            action="dispatch_worker_cli",
+            detail=str(exc) or exc.__class__.__name__,
+        )
+    finally:
+        for signum, previous in previous_handlers.items():
+            try:
+                signal.signal(signum, previous)
+            except (ValueError, OSError):
+                continue
+    shutdown_error: PzError | None = None
+    shutdown_cause: Exception | None = None
+    try:
+        started.shutdown(reason=shutdown_reason)
+    except Exception as exc:
+        shutdown_cause = exc
+        shutdown_error = as_pz_error(
+            exc,
+            code="PZ_WORKER_SHUTDOWN_FAILED",
+            stage="worker",
+            owner=app_id or "runtime.worker",
+            action="shutdown_worker_runtime",
+        )
+    if primary_error is not None and shutdown_error is not None:
+        fragments: list[str] = []
+        if primary_error.detail:
+            fragments.append(primary_error.detail)
+        fragments.append(
+            f"shutdown[{shutdown_error.owner}:{shutdown_error.action}:{shutdown_error.code}] "
+            f"{shutdown_error.summary or shutdown_error.message}"
+        )
+        primary_error.detail = " | ".join(fragments)
+        raise primary_error from primary_cause
+    if primary_error is not None:
+        raise primary_error from primary_cause
+    if shutdown_error is not None:
+        raise shutdown_error from shutdown_cause
+    return result_code if result_code is not None else 0
+
+
+def create_worker_runtime(
+    project_dir: str | Path | None = None,
+    *,
+    installed_apps: tuple[str, ...] | None = None,
+    app_id: str | None = None,
+    tool_name: str | None = None,
+    replica_slot: int | None = None,
+    once: bool = False,
+    concurrency: int | None = None,
+    poll_interval_seconds: float | None = None,
+    shutdown_timeout_seconds: float | None = None,
+) -> WorkerRuntime:
+    plan = compile_runtime_plan(
+        project_dir=project_dir,
+        installed_apps=installed_apps,
+        include_cli_manifest=False,
+    )
+    state = bind_runtime_plan(plan)
+    bindings = compile_runtime_bindings(plan, state)
+    session = _compile_worker_session(
+        plan,
+        app_id=app_id,
+        tool_name=tool_name,
+        replica_slot=replica_slot,
+        once=once,
+        concurrency=concurrency,
+        poll_interval_seconds=poll_interval_seconds,
+        shutdown_timeout_seconds=shutdown_timeout_seconds,
+    )
+    return WorkerRuntime(
+        adapter=RuntimeAdapter(kind="worker", plan=plan, state=state, bindings=bindings),
+        session=session,
+        app_id=app_id,
+        tool_name=tool_name,
+        control=WorkerControl(),
+    )