procesio-cli 0.1.1__py3-none-any.whl

procesio_cli/tools/_lib/userdata.py

@@ -0,0 +1,228 @@
+"""Single resolver for WHERE user-specific data lives.
+
+North star: the framework (tools/, agents/, skills/, scripts/) carries ZERO
+user-specific data. Everything user-specific - config, runtime state, knowledge,
+resources, preferences, decisions, run history, saved sessions - lives under one
+folder, ``context-state-knowledge/`` at the repo root. That folder is never
+git-versioned (see .gitignore) and is safe to wipe: delete it and the framework
+runs clean for a brand-new user.
+
+This module is the ONE place that knows that path, so tools AND agents resolve
+user-data locations the same way and a future move needs a single change here.
+Agents already import ``tools._lib`` (creds, io), so this lives here rather than
+in ``agents/_lib`` to be importable by both without a cross-package dependency.
+
+Relocatable: set ``AAT_USERDATA_DIR`` to move the whole user-data root to another
+path or laptop with no code change (serves the LLM-agnostic / portable direction).
+
+Installed rather than cloned: when this ships inside a wheel there IS no repo root to
+sit beside, so user data goes to the platform's per-user data directory instead. It must
+never land inside the installation: that directory is replaced on upgrade (taking the
+credentials config and run history with it), can need admin rights to write on a
+system-wide install, and is shared by every account on the machine.
+
+Layout under the base:
+
+    context-state-knowledge/
+      store.db            # SQLite (context-store tool)
+      state/<component>/  # per-agent/tool runtime state
+      config/<component>/ # per-agent/tool user config
+      prompts/<component>/# per-user prompt copies (base+personal, agents/_lib/prompts.py)
+      sessions/           # relocated web login profiles
+      exports/            # human-readable dumps
+
+Pure path resolution + ensure-exists. Seeding docs/DB schema is the job of the
+context-store tool and the curator/orchestrator agents, not this module.
+"""
+from __future__ import annotations
+
+import os
+import re
+import sys
+from pathlib import Path
+
+# tools/_lib/userdata.py -> parents[2] == repo root
+_REPO_ROOT = Path(__file__).resolve().parents[2]
+_ENV_VAR = "AAT_USERDATA_DIR"
+_USER_ENV = "AAT_USER_ID"
+_WORKSPACE_ENV = "AAT_WORKSPACE_ID"
+_DEFAULT_DIRNAME = "context-state-knowledge"
+
+_SAFE = re.compile(r"[^0-9A-Za-z._-]+")
+
+
+def _safe_component(name: str) -> str:
+    """Sanitize a component name into a single safe path segment.
+
+    Prevents path traversal (no separators, no ``..``) so a caller-supplied
+    agent/tool name can never escape the user-data root.
+    """
+    if not name or not str(name).strip():
+        raise ValueError("component name must be a non-empty string")
+    seg = _SAFE.sub("-", str(name).strip()).strip("-._")
+    if not seg or seg in (".", ".."):
+        raise ValueError(f"invalid component name: {name!r}")
+    return seg
+
+
+def _is_checkout() -> bool:
+    """True when running from a clone rather than an installed package.
+
+    A checkout carries its own ``pyproject.toml`` beside the tree; a wheel installs the
+    tree without it. That is the cheapest honest signal - matching on "site-packages" in
+    the path guesses at a layout that varies by installer, platform and editable install.
+    """
+    return (_REPO_ROOT / "pyproject.toml").is_file()
+
+
+def _platform_data_dir() -> Path:
+    """The per-user data directory, by platform convention. Standard library only."""
+    if os.name == "nt":
+        base = os.environ.get("LOCALAPPDATA") or r"~\AppData\Local"
+    elif sys.platform == "darwin":
+        base = "~/Library/Application Support"
+    else:
+        base = os.environ.get("XDG_DATA_HOME") or "~/.local/share"
+    return Path(base).expanduser() / "procesio-cli"
+
+
+def _root() -> Path:
+    override = os.environ.get(_ENV_VAR)
+    if override:
+        return Path(override).expanduser()
+    if _is_checkout():
+        return _REPO_ROOT / _DEFAULT_DIRNAME
+    return _platform_data_dir()
+
+
+def current_user() -> str | None:
+    """The active user id (``AAT_USER_ID``), sanitized to a single safe path segment,
+    or None in single-user mode. The multi-user web platform sets this per request
+    (server-established from the authenticated session, never from model output)."""
+    uid = os.environ.get(_USER_ENV)
+    return _safe_component(uid) if uid and str(uid).strip() else None
+
+
+def current_workspace() -> str | None:
+    """The active workspace id (``AAT_WORKSPACE_ID``), sanitized to a single safe path
+    segment, or None. The multi-tenant PROCESIO module sets this per request alongside
+    ``AAT_USER_ID`` (server-established from the authenticated session, never from model
+    output). Unset = no workspace dimension, exactly the historical single-workspace
+    behaviour, so local Claude Code is unaffected. Personal-workspace semantics
+    (PROCESIO ``Guid.Empty``) are the caller's concern - this resolver only sees an id."""
+    ws = os.environ.get(_WORKSPACE_ENV)
+    return _safe_component(ws) if ws and str(ws).strip() else None
+
+
+def base() -> Path:
+    """The user-data root. Honors ``AAT_USERDATA_DIR`` (the root) and ``AAT_USER_ID``
+    (a per-user subdir under it, for the multi-user web platform). Defaults to the
+    repo's ``context-state-knowledge/``. **Unset AAT_USER_ID = single-user, exactly as
+    before** - so local Claude Code is unaffected. Every other resolver here derives
+    from ``base()``, so per-user isolation is automatic (store.db, state, config,
+    prompts, sessions, schedule, exports all move under the user's subdir). Created on
+    first access.
+
+    **Workspace dimension (``AAT_WORKSPACE_ID``):** when set, a ``ws/<ws>`` segment is
+    inserted BEFORE the user segment, so the data root is ``<root>/ws/<ws>/<user>`` -
+    isolating per ``(workspace, user)`` for the multi-tenant PROCESIO module. **Unset =
+    exactly today's paths** (``<root>`` or ``<root>/<user>``), so nothing local moves."""
+    root = _root()
+    ws = current_workspace()
+    if ws:
+        root = root / "ws" / ws
+    uid = current_user()
+    if uid:
+        root = root / uid
+    root.mkdir(parents=True, exist_ok=True)
+    return root
+
+
+def store_db_path() -> Path:
+    """Path to the SQLite store file (parent ensured, file not created here)."""
+    base()  # ensure root exists
+    return base() / "store.db"
+
+
+def state_dir(component: str) -> Path:
+    """Per-component runtime state dir, e.g. state_dir('email-classifier')."""
+    p = base() / "state" / _safe_component(component)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def config_dir(component: str) -> Path:
+    """Per-component user config dir, e.g. config_dir('mysql')."""
+    p = base() / "config" / _safe_component(component)
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def prompts_dir(component: str, *, create: bool = True) -> Path:
+    """Per-agent personal prompt copies live here (base+personal versioning;
+    agents/_lib/prompts.py). Wipe = agents fall back to their framework base
+    prompts. ``create=False`` for read paths so resolving a prompt never leaves
+    an empty dir behind."""
+    p = base() / "prompts" / _safe_component(component)
+    if create:
+        p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def sessions_dir() -> Path:
+    """Relocated web login profiles / broker state live here."""
+    p = base() / "sessions"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def exports_dir() -> Path:
+    """Human-readable dumps written by the curator live here."""
+    p = base() / "exports"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def schedule_dir() -> Path:
+    """The user's recurring-work schedule (schedule/*.yaml declarative entries +
+    machine-owned state.json/log.jsonl). Read and executed by the orchestrator's
+    schedule-tick; user data like everything else here - wipe = no scheduled work."""
+    p = base() / "schedule"
+    p.mkdir(parents=True, exist_ok=True)
+    return p
+
+
+def describe() -> dict:
+    """Small status view for orchestrator/curator health reporting."""
+    b = base()
+    return {
+        "base": str(b),
+        "overridden": bool(os.environ.get(_ENV_VAR)),
+        "env_var": _ENV_VAR,
+        "user": current_user(),
+        "multi_user": current_user() is not None,
+        "workspace": current_workspace(),
+        "multi_tenant": current_workspace() is not None,
+        "store_db": str(b / "store.db"),
+        "store_db_exists": (b / "store.db").exists(),
+    }
+
+
+def scan() -> dict:
+    """File counts across the user-data areas. This is how agents detect a fresh
+    start: a wiped folder never breaks the framework - it just scans as empty and
+    the orchestrator/curator prompt the user to start building (templates live
+    beside each component as <name>.template.json; `orchestrator bootstrap` seeds)."""
+    b = base()
+
+    def count(p: Path) -> int:
+        return sum(1 for x in p.rglob("*") if x.is_file()) if p.exists() else 0
+
+    return {
+        "store_db_exists": (b / "store.db").exists(),
+        "config_files": count(b / "config"),
+        "state_files": count(b / "state"),
+        "session_files": count(b / "sessions"),
+        "export_files": count(b / "exports"),
+        "readme_exists": (b / "README.md").exists(),
+    }

procesio_cli/tools/_lib/webserialize/__init__.py

@@ -0,0 +1,16 @@
+"""webserialize — per-tool serializing brokers for persistent web profiles.
+
+Two processes driving the same browser profile concurrently corrupt/invalidate
+the web app's session (Chromium SingletonLock). This lib gives each tool ONE
+broker process that owns its profile and executes commands strictly one at a
+time; clients (the tool's own dispatch, and the generic web tool) submit over
+a tiny local JSONL protocol.
+
+Reference integration: tools/whatsapp-personal (v0.2.0 originated the pattern,
+now a thin adapter over this lib). Registry of brokers/ports/owned sessions:
+tools/_lib/webserialize/registry.py.
+"""
+from tools._lib.webserialize.config import HOST, PROTO, BrokerConfig  # noqa: F401
+from tools._lib.webserialize.errors import (  # noqa: F401
+    ServiceError, ServiceRemoteError,
+)

procesio_cli/tools/_lib/webserialize/admin.py

@@ -0,0 +1,61 @@
+"""The three service-admin actions every broker-backed tool exposes.
+
+These are plain functions over a BrokerConfig; each tool wraps them in its own
+ActionDef (needs_driver/needs_client False) so they never route and always
+work — even when the service is wedged.
+"""
+from __future__ import annotations
+
+from tools._lib.webserialize import client, runtime
+from tools._lib.webserialize.config import BrokerConfig
+from tools._lib.webserialize.errors import ServiceError
+
+
+def service_status(cfg: BrokerConfig) -> dict:
+    pong = client.ping(cfg)
+    if pong is None:
+        return {
+            "running": False,
+            "tool": cfg.tool,
+            "port": cfg.effective_port(),
+            "note": "no service is listening; it auto-starts on the next "
+                    "browser action (or run service-start)",
+            "stale_state_file": runtime.read_state(cfg),
+            "log": str(cfg.log_path),
+        }
+    status = client.request_status(cfg) or {}
+    status.setdefault("running", True)
+    status["port"] = cfg.effective_port()
+    status["code_current"] = pong.get("code_stamp") == runtime.code_stamp(cfg)
+    if not status["code_current"]:
+        status["note"] = ("service runs STALE code (tool edited since it "
+                          "started); the next routed command restarts it "
+                          "automatically, or run service-stop + service-start")
+    return status
+
+
+def service_start(cfg: BrokerConfig) -> dict:
+    pong = client.ensure_running(cfg)
+    if pong is None:
+        raise ServiceError(
+            f"could not start the {cfg.tool} service; check "
+            f"{cfg.spawn_err_path} and {cfg.log_path}"
+        )
+    status = client.request_status(cfg) or {}
+    return {"running": True, "pid": pong.get("pid"),
+            "port": cfg.effective_port(), "status": status}
+
+
+def service_stop(cfg: BrokerConfig, *, wait_s: float = 60) -> dict:
+    was_running = client.ping(cfg) is not None
+    stopped = client.stop(cfg, wait_s=wait_s)
+    out = {"was_running": was_running, "stopped": stopped,
+           "tool": cfg.tool, "port": cfg.effective_port()}
+    if not stopped:
+        out["note"] = ("service did not exit within the wait window "
+                       "(a long command may be mid-flight); re-run, or check "
+                       f"{cfg.log_path}")
+    else:
+        out["note"] = ("profile released — safe to log in "
+                       "(web save-session) or use --direct")
+    return out

procesio_cli/tools/_lib/webserialize/client.py

@@ -0,0 +1,264 @@
+"""Client side of a serializing broker. Every function takes the tool's
+BrokerConfig first; tools call these from their dispatch routing.
+
+Safety rules (they matter for message/state-changing commands):
+
+  * FALLBACK TO DIRECT happens ONLY when the request was never submitted —
+    no service answered and one could not be started. Running direct then is
+    safe because the failed service never opened a browser.
+  * Once a request has been SENT, a lost connection NEVER falls back: the
+    command may be mid-flight, and re-running could double-send.
+  * A running service built from STALE code (the tool was edited since it
+    started) is detected via ``code_stamp`` and transparently restarted.
+"""
+from __future__ import annotations
+
+import os
+import socket
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from tools._lib.webserialize import framing, runtime
+from tools._lib.webserialize.config import HOST, PROTO, FRAMEWORK_ROOT, BrokerConfig
+from tools._lib.webserialize.errors import ServiceError, ServiceRemoteError
+
+_CONNECT_TIMEOUT_S = 5
+_SPAWN_WAIT_S = 25
+_STOP_WAIT_S = 60
+
+
+# --------------------------------------------------------------------------- #
+# Routing decision
+# --------------------------------------------------------------------------- #
+def enabled(cfg: BrokerConfig) -> bool:
+    """Routing is ON unless explicitly disabled or we ARE the service worker."""
+    if runtime.env_truthy(cfg.direct_env):
+        return False
+    if runtime.env_truthy(cfg.worker_env):
+        return False
+    return True
+
+
+# --------------------------------------------------------------------------- #
+# Wire helpers
+# --------------------------------------------------------------------------- #
+def _request(cfg: BrokerConfig, obj: dict, *, read_timeout: float,
+             port: int | None = None) -> dict:
+    """Send one framed request, wait for the one framed response.
+
+    Connect+send failures raise OSError (caller may safely fall back: nothing
+    was accepted). After the request is on the wire, read failures raise
+    ServiceError (NOT safe to fall back)."""
+    port = port or cfg.effective_port()
+    s = socket.create_connection((HOST, port), timeout=_CONNECT_TIMEOUT_S)
+    try:
+        s.sendall(framing.encode(obj))            # OSError here -> not submitted
+        s.settimeout(read_timeout)
+        try:
+            raw = framing.recv_line(s)
+        except (OSError, ValueError) as exc:
+            raise ServiceError(
+                f"lost the {cfg.tool} service mid-request "
+                f"({exc.__class__.__name__}: {exc}). The command MAY still be "
+                "executing — check `service-status` and the target system "
+                "before retrying a state-changing command."
+            ) from exc
+        if not raw.strip():
+            raise ServiceError(
+                f"the {cfg.tool} service closed the connection without a "
+                "response. The command MAY have executed — verify before retrying."
+            )
+        return framing.decode(raw)
+    finally:
+        try:
+            s.close()
+        except OSError:
+            pass
+
+
+def ping(cfg: BrokerConfig, *, timeout: float = 2.0,
+         port: int | None = None) -> dict | None:
+    try:
+        resp = _request(cfg, {"op": "ping"}, read_timeout=timeout, port=port)
+    except (OSError, ServiceError, ValueError):
+        return None
+    if resp.get("ok") and (resp.get("result") or {}).get("pong"):
+        return resp["result"]
+    return None
+
+
+def request_status(cfg: BrokerConfig, *, port: int | None = None) -> dict | None:
+    try:
+        resp = _request(cfg, {"op": "status"}, read_timeout=10, port=port)
+    except (OSError, ServiceError, ValueError):
+        return None
+    return resp.get("result") if resp.get("ok") else None
+
+
+def stop(cfg: BrokerConfig, *, wait_s: float = _STOP_WAIT_S,
+         port: int | None = None) -> bool:
+    """Ask the service to stop; True when it is gone (or was never running)."""
+    if ping(cfg, port=port) is None:
+        return True
+    try:
+        _request(cfg, {"op": "stop"}, read_timeout=10, port=port)
+    except (OSError, ServiceError, ValueError):
+        pass
+    deadline = time.time() + wait_s
+    while time.time() < deadline:
+        if ping(cfg, port=port) is None:
+            return True
+        time.sleep(0.3)
+    return False
+
+
+# --------------------------------------------------------------------------- #
+# Lifecycle
+# --------------------------------------------------------------------------- #
+def spawn(cfg: BrokerConfig) -> int:
+    """Start the tool's service DETACHED. Startup errors land in
+    .service/spawn-err.log; runtime logs in service.log."""
+    py = runtime.venv_python() or Path(sys.executable)
+    cfg.service_dir.mkdir(parents=True, exist_ok=True)
+    err = open(cfg.spawn_err_path, "ab")
+    kwargs: dict = dict(stdin=subprocess.DEVNULL, stdout=subprocess.DEVNULL,
+                        stderr=err, close_fds=True, cwd=str(FRAMEWORK_ROOT))
+    if os.name == "nt":
+        # CREATE_NO_WINDOW | CREATE_NEW_PROCESS_GROUP
+        kwargs["creationflags"] = 0x08000000 | 0x00000200
+    else:
+        kwargs["start_new_session"] = True
+    try:
+        proc = subprocess.Popen([str(py), str(cfg.service_py)], **kwargs)
+    finally:
+        err.close()
+    return proc.pid
+
+
+def ensure_running(cfg: BrokerConfig, *, port: int | None = None) -> dict | None:
+    """Make sure a CURRENT-code service is up. Returns its ping payload, or
+    None when one could not be started (caller falls back to direct)."""
+    pong = ping(cfg, port=port)
+    if pong is not None:
+        stale = (pong.get("proto") != PROTO
+                 or pong.get("code_stamp") != runtime.code_stamp(cfg))
+        if not stale:
+            return pong
+        # Stale daemon: restart. If it will not die, keep using it (it still
+        # serializes correctly; it just runs older code).
+        if not stop(cfg, port=port):
+            return pong
+    try:
+        spawn(cfg)
+    except OSError:
+        return None
+    deadline = time.time() + _SPAWN_WAIT_S
+    while time.time() < deadline:
+        pong = ping(cfg, port=port)
+        if pong is not None:
+            return pong
+        time.sleep(0.25)
+    return None
+
+
+# --------------------------------------------------------------------------- #
+# The calls used by tool dispatchers
+# --------------------------------------------------------------------------- #
+def _timeout_for(cfg: BrokerConfig, parsed) -> float:
+    """Generous per-request wait: the action's own waits plus queue allowance
+    (other sessions' commands run first). Env override wins."""
+    raw = os.environ.get(cfg.timeout_env, "")
+    if raw.strip():
+        try:
+            return float(raw)
+        except ValueError:
+            pass
+    wait_ms = getattr(parsed, "wait", 0) or 0
+    reply_ms = getattr(parsed, "timeout", 0) or 0
+    est = 120 + 2 * (wait_ms / 1000.0) + (reply_ms / 1000.0)
+    return max(900.0, est + 600.0)
+
+
+def _tag(result, resp: dict, via: str):
+    if isinstance(result, dict):
+        result.setdefault("via", via)
+        if "queue_wait_ms" in resp:
+            result.setdefault("service_queue_wait_ms", resp["queue_wait_ms"])
+    return result
+
+
+def _raise_remote(resp: dict):
+    err = resp.get("error") or {}
+    raise ServiceRemoteError(
+        err.get("code") or "error",
+        err.get("message") or "service reported an error",
+        err.get("details") or {},
+        int(resp.get("exit_code") or 1),
+    )
+
+
+def call(cfg: BrokerConfig, action: str, argv: list[str], parsed, *,
+         dispatch_direct) -> dict:
+    """Run a TOOL ACTION through the broker. ``dispatch_direct(action, argv)``
+    is the in-process fallback, used ONLY when nothing was ever submitted."""
+    pong = ensure_running(cfg)
+    if pong is None:
+        result = dispatch_direct(action, argv)
+        if isinstance(result, dict):
+            result.setdefault("via", "direct-fallback")
+            result.setdefault(
+                "service_fallback",
+                f"the {cfg.tool} serializing service could not be started; "
+                f"executed in-process instead (see {cfg.spawn_err_path})")
+        return result
+    try:
+        resp = _request(cfg, {"op": "run", "action": action, "argv": list(argv)},
+                        read_timeout=_timeout_for(cfg, parsed))
+    except OSError as exc:
+        # Connect/send failed AFTER a good ping — the service just died and
+        # nothing was submitted, so direct is still safe.
+        result = dispatch_direct(action, argv)
+        if isinstance(result, dict):
+            result.setdefault("via", "direct-fallback")
+            result.setdefault("service_fallback",
+                              f"service vanished before accepting the request "
+                              f"({exc.__class__.__name__}); executed in-process")
+        return result
+    if resp.get("ok"):
+        return _tag(resp.get("result"), resp, "service")
+    _raise_remote(resp)
+
+
+def web_steps(cfg: BrokerConfig, session: str, steps: list, *, url=None,
+              headless: bool = True, read_timeout: float | None = None,
+              dispatch_direct=None) -> dict:
+    """Run a GENERIC web-tool step list through the broker owning ``session``
+    (how `web run/get-text/screenshot` stay serialized). Same fallback rules
+    as ``call``: ``dispatch_direct()`` (no args) only when never submitted."""
+    pong = ensure_running(cfg)
+    if pong is None:
+        if dispatch_direct is None:
+            raise ServiceError(
+                f"the {cfg.tool} service (owner of session {session!r}) could "
+                f"not be started; see {cfg.spawn_err_path}")
+        result = dispatch_direct()
+        if isinstance(result, dict):
+            result.setdefault("via", "direct-fallback")
+        return result
+    req = {"op": "web-steps", "session": session, "steps": steps,
+           "url": url, "headless": headless}
+    try:
+        resp = _request(cfg, req, read_timeout=read_timeout or 900.0)
+    except OSError:
+        if dispatch_direct is None:
+            raise ServiceError(
+                f"the {cfg.tool} service vanished before accepting the request")
+        result = dispatch_direct()
+        if isinstance(result, dict):
+            result.setdefault("via", "direct-fallback")
+        return result
+    if resp.get("ok"):
+        return _tag(resp.get("result"), resp, "service")
+    _raise_remote(resp)

procesio_cli/tools/_lib/webserialize/config.py

@@ -0,0 +1,96 @@
+"""BrokerConfig — everything that parameterizes one tool's serializing broker.
+
+One broker per tool, one fixed localhost port per broker (binding the port IS
+the single-instance guard), one `.service/` runtime dir under the tool root.
+The env-var names are derived from ``env_prefix`` so every tool gets the same
+knobs (`<PREFIX>_DIRECT`, `<PREFIX>_SERVICE_PORT`, ...) — for
+``whatsapp-personal`` the prefix is ``WHATSAPP``, which keeps the original
+variable names working unchanged.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+PROTO = 1
+HOST = "127.0.0.1"
+
+DEFAULT_IDLE_CLOSE_S = 120     # close the warm browser after this much idle
+DEFAULT_EXIT_IDLE_S = 86400    # exit the service process after this much idle
+
+# tools/_lib/webserialize/config.py -> repo root
+FRAMEWORK_ROOT = Path(__file__).resolve().parents[3]
+TOOLS_ROOT = FRAMEWORK_ROOT / "tools"
+LIB_DIR = Path(__file__).resolve().parent
+
+
+@dataclass(frozen=True)
+class BrokerConfig:
+    tool: str                      # registry key, e.g. "whatsapp-personal"
+    port: int                      # fixed default port (env can override)
+    env_prefix: str                # "WHATSAPP" -> WHATSAPP_DIRECT, ...
+    sessions: tuple[str, ...]      # persistent-profile session names it OWNS
+    code_dirs: tuple[Path, ...] = field(default=())  # *.py dirs for code_stamp
+
+    # --- paths --------------------------------------------------------------
+    @property
+    def tool_root(self) -> Path:
+        return TOOLS_ROOT / self.tool
+
+    @property
+    def service_py(self) -> Path:
+        return self.tool_root / "service.py"
+
+    @property
+    def service_dir(self) -> Path:
+        return self.tool_root / ".service"
+
+    @property
+    def state_path(self) -> Path:
+        return self.service_dir / "state.json"
+
+    @property
+    def log_path(self) -> Path:
+        return self.service_dir / "service.log"
+
+    @property
+    def spawn_err_path(self) -> Path:
+        return self.service_dir / "spawn-err.log"
+
+    # --- env knobs ------------------------------------------------------------
+    @property
+    def direct_env(self) -> str:
+        return f"{self.env_prefix}_DIRECT"
+
+    @property
+    def worker_env(self) -> str:
+        return f"{self.env_prefix}_SERVICE_WORKER"
+
+    @property
+    def port_env(self) -> str:
+        return f"{self.env_prefix}_SERVICE_PORT"
+
+    @property
+    def timeout_env(self) -> str:
+        return f"{self.env_prefix}_SERVICE_TIMEOUT_S"
+
+    @property
+    def idle_close_env(self) -> str:
+        return f"{self.env_prefix}_SERVICE_IDLE_S"
+
+    @property
+    def exit_idle_env(self) -> str:
+        return f"{self.env_prefix}_SERVICE_EXIT_S"
+
+    def effective_port(self) -> int:
+        raw = os.environ.get(self.port_env, "")
+        try:
+            return int(raw) if raw.strip() else self.port
+        except ValueError:
+            return self.port
+
+    def stamp_dirs(self) -> tuple[Path, ...]:
+        """Dirs whose *.py mtimes form the code stamp. The lib itself is always
+        included: a webserialize change must restart every broker."""
+        return tuple(self.code_dirs) + (LIB_DIR,)