Self-improving AI Employees for everyone
Python ai-agentsai-employeeai-employeesassistantautonomous-agentsco-employeescompanygrok-botinstinctloop-agentsmuseown-your-datapersonalself-hosted
refactor(cli): make machina clean recovery-resilient + extract _common helpers
trohitg18e0522456a9
diff --git a/cli/_common.py b/cli/_common.pynew file mode 100644index 00000000..789986fb--- /dev/null+++ b/cli/_common.py@@ -0,0 +1,115 @@+"""Cross-verb helpers shared by ``machina`` commands.++Centralises the four patterns that previously appeared inlined in+``start.py`` / ``dev.py`` / ``stop.py`` / ``clean.py`` / ``build.py``:++ - :func:`preflight` -- ``load_config()`` + ``project_root()``+ preamble every verb opens with.+ - :func:`free_all_ports` -- ``for port in cfg.all_ports: kill_port``+ loop; lazy-imports ``cli.ports`` so a+ broken ``psutil`` install doesn't take+ down the recovery verb.+ - :func:`build_backend_spec` -- the shared ``uv_run("uvicorn", ...)``+ ServiceSpec used by both ``start``+ and ``dev``.+ - :func:`error_block` -- multi-line ``[red]Error: ...[/]``+ formatter; lazy-imports ``cli.colors``.++No third-party packages are imported at module load time. Importing+this module from ``cli/commands/clean.py`` is safe even when+``rich`` / ``psutil`` / ``platformdirs`` are missing -- only the+helper that actually needs the dep pulls it in.+"""++from __future__ import annotations++from pathlib import Path+from typing import TYPE_CHECKING++from cli.config import Config, load_config+from cli.platform_ import project_root, server_dir++if TYPE_CHECKING:+ from cli.ports import KillResult+ from cli.supervisor import ServiceSpec++# ``cli.run`` (and ``cli.supervisor`` via ``cli.colors``) transitively+# pull in ``rich``. They're only needed by ``build_backend_spec`` /+# ``error_block`` which themselves lazy-import. Keeping them out of the+# top-level import list means ``machina clean`` (which calls only+# ``preflight`` and ``free_all_ports``) loads even when ``rich`` /+# ``psutil`` / ``platformdirs`` are unavailable.+++def preflight(cfg: Config | None = None) -> tuple[Config, Path]:+ """Standard verb preamble: ``(load_config(), project_root())``.++ Pass an explicit ``cfg`` to avoid the lookup (e.g. when the caller+ already has one). ``load_config`` is ``@lru_cache``d, so repeated+ calls inside the same process are free regardless.+ """+ return cfg or load_config(), project_root()+++def free_all_ports(cfg: Config) -> list[KillResult]:+ """Kill anything listening on ``cfg.all_ports``; return per-port+ results.++ Returns a list (not a count) so callers can render per-port status+ -- ``machina stop`` shows ``[OK]`` / ``[!!]`` markers and the killed+ PIDs, ``machina start`` and ``clean`` just want them gone. The+ helper centralises the iteration, callers pick the rendering.++ ``cli.ports`` is imported lazily so this module loads even when+ ``psutil`` (a transitive dep) is missing -- important for the+ recovery verb ``machina clean``.+ """+ from cli.ports import kill_port+ return [kill_port(port) for port in cfg.all_ports]+++def build_backend_spec(+ cfg: Config,+ *,+ host: str,+ root: Path | None = None,+) -> "ServiceSpec":+ """The Python backend ``ServiceSpec`` shared by ``start`` and ``dev``.++ Routes through :func:`cli.run.uv_run` so the standardised+ ``uv run --no-sync`` flags stay in one place. ``host`` is the only+ differentiator (``start`` picks ``127.0.0.1`` on Windows/WSL vs+ ``0.0.0.0`` elsewhere; ``dev`` honours its ``--daemon`` flag).++ ``cli.run`` and ``cli.supervisor`` are lazy-imported so this module+ stays importable when their transitive ``rich`` dep is missing --+ ``machina clean`` doesn't call this and shouldn't pay for it.+ """+ from cli.run import uv_run+ from cli.supervisor import ServiceSpec+ return ServiceSpec(+ name="server",+ argv=uv_run(+ "uvicorn", "main:app",+ "--host", host,+ "--port", str(cfg.backend_port),+ "--log-level", "warning",+ ),+ cwd=server_dir(root),+ ready_port=cfg.backend_port,+ )+++def error_block(title: str, lines: list[str]) -> None:+ """Print a multi-line ``[red]Error: ...[/]`` block, indented body.++ ``cli.colors`` is imported lazily so this module remains+ importable without ``rich``. Anything heavier (e.g., remediation+ URLs, code snippets) goes in ``lines`` -- it's rendered as plain+ ``console.print`` calls so rich BBCode in callers' strings still+ interprets.+ """+ from cli.colors import console+ console.print(f"[red]Error: {title}[/]")+ for line in lines:+ console.print(f" {line}")diff --git a/cli/buildenv.py b/cli/buildenv.pyindex 52bf1e71..900182ac 100644--- a/cli/buildenv.py+++ b/cli/buildenv.py@@ -1,8 +1,14 @@"""Build-environment helpers shared by ``start`` / ``dev`` / ``daemon``.-Three commands had near-duplicate copies of "find the venv python" and-"the build artifacts must exist or refuse to start". Lifted here so a-new launcher gets both for free.+``validate_build`` refuses to launch when ``machina build`` hasn't been+run. Layout knowledge lives in :mod:`cli.platform_` -- this file only+composes the documented prefixes (workspace venv, node_modules, client+dist) into a boolean check.++Subprocess callers (start / dev / daemon / temporal specs) build their+argv via :func:`cli.run.uv_run`, which runs the command inside the uv+workspace ``.venv`` per https://docs.astral.sh/uv/reference/cli/#uv-run.+There is no path-to-interpreter logic on the CLI side -- uv owns that."""from __future__ import annotations@@ -12,21 +18,11 @@ from pathlib import Pathimport typerfrom cli.colors import console---def venv_python(root: Path) -> Path | None:- """Return the project's venv python path, or ``None`` if absent.-- Tries the Windows layout first (``Scripts/python.exe``) then POSIX- (``bin/python``); the first existing path wins.- """- for candidate in (- root / "server" / ".venv" / "Scripts" / "python.exe",- root / "server" / ".venv" / "bin" / "python",- ):- if candidate.exists():- return candidate- return None+from cli.platform_ import (+ client_dist_entry,+ node_modules_dir,+ server_venv,+)def validate_build(root: Path, *, require_client_dist: bool = False) -> None:@@ -36,9 +32,9 @@ def validate_build(root: Path, *, require_client_dist: bool = False) -> None:missing ``client/dist`` (Vite serves the source); ``start`` opts invia ``require_client_dist=True``."""- if not (root / "node_modules").exists() or not (root / "server" / ".venv").exists():+ if not node_modules_dir(root).exists() or not server_venv(root).exists():console.print('[red]Error: Project not built. Run "machina build" first.[/]')raise typer.Exit(code=1)- if require_client_dist and not (root / "client" / "dist" / "index.html").exists():+ if require_client_dist and not client_dist_entry(root).exists():console.print('[red]Error: Client not built. Run "machina build" first.[/]')raise typer.Exit(code=1)diff --git a/cli/commands/_temporal_specs.py b/cli/commands/_temporal_specs.pyindex 1d4ca0a6..37bb6f54 100644--- a/cli/commands/_temporal_specs.py+++ b/cli/commands/_temporal_specs.py@@ -8,7 +8,8 @@ Returns the right Temporal ``ServiceSpec`` set based on- ``postgres`` (default) — two specs running the supervised runtimes:``temporal-postgres`` (pgserver) then ``temporal-server`` (Temporalbinary with YAML config). Both wrap ``BaseSupervisor`` singletons- via ``cli.commands._supervised_runtime``. Data lands under+ via ``services.temporal._supervised_runtime`` (a thin shim that+ lives next to the runtime factories it imports). Data lands under``DATA_DIR/postgres/``; binaries come from a pooch-managed cache(no system install required).@@ -32,6 +33,8 @@ from __future__ import annotationsimport osfrom pathlib import Path+from cli.platform_ import server_dir+from cli.run import uv_runfrom cli.supervisor import RestartPolicy, ServiceSpec# Backend names — must match ``core.config.Settings.temporal_backend``@@ -65,12 +68,18 @@ _GRACE_SECONDS = float(def _runtime_argv(factory_path: str) -> list[str]:"""Build the argv for one BaseSupervisor singleton, invoked via thegeneric supervised-runtime shim. ``factory_path`` is the dotted- ``module:attr`` accessor."""- return [- "uv", "run", "python", "-m",- "cli.commands._supervised_runtime",+ ``module:attr`` accessor.++ Composes the uv invocation through :func:`cli.run.uv_run` so every+ ``uv run --no-sync`` callsite in the CLI shares the same flag set.+ The shim itself lives at ``services.temporal._supervised_runtime``+ (next to the runtime factories), so the spawned python only needs+ to resolve modules out of the workspace ``.venv``.+ """+ return uv_run(+ "python", "-m", "services.temporal._supervised_runtime",factory_path,- ]+ )def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:@@ -81,14 +90,14 @@ def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:readiness probe (same port for both ``sqlite`` and ``postgres``)."""backend = cfg.temporal_backend.strip().lower()- server_dir = root / "server"+ server_cwd = server_dir(root)if backend == _BACKEND_POSTGRES:return [ServiceSpec(name="postgres",argv=_runtime_argv("services.temporal._runtime:get_postgres_runtime"),- cwd=server_dir,+ cwd=server_cwd,# pgserver picks a dynamic port; skip the TCP probe here# and rely on the temporal spec to gate readiness via# gRPC (it can't connect until Postgres accepts).@@ -102,7 +111,7 @@ def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:argv=_runtime_argv("services.temporal._runtime:get_temporal_server_runtime",),- cwd=server_dir,+ cwd=server_cwd,ready_port=cfg.temporal_port,ready_timeout=_SERVER_READY_TIMEOUT_SECONDS,restart=RestartPolicy.ON_CRASH,@@ -122,7 +131,7 @@ def temporal_specs(root: Path, cfg) -> list[ServiceSpec]:argv=_runtime_argv("services.temporal._runtime:get_temporal_server_runtime",),- cwd=server_dir,+ cwd=server_cwd,ready_port=cfg.temporal_port,ready_timeout=_SERVER_READY_TIMEOUT_SECONDS,restart=RestartPolicy.ON_CRASH,diff --git a/cli/commands/clean.py b/cli/commands/clean.pyindex c9c25cad..086cbb4f 100644--- a/cli/commands/clean.py+++ b/cli/commands/clean.py@@ -1,8 +1,16 @@-"""``machina clean`` — reset the repo to a fresh-checkout state.--Stops every process listening on the configured ports + orphaned project-processes, waits for file locks to release, then removes build artefacts-and venvs.+"""``machina clean`` -- reset the repo to a fresh-checkout state.++Recovery verb: must work even when the env is partially broken+(missing ``rich`` / ``psutil`` / ``platformdirs`` wheels, half-wiped+``server/.venv``, etc.). Everything at module load is stdlib + first-party+helpers (``cli._common`` / ``cli.config`` / ``cli.platform_``). The+process-killing step (which needs ``psutil`` via :mod:`cli.ports`) is+lazy-imported inside :func:`clean_command` and degrades to a warning+if the wheel is missing -- file removal continues regardless.++Stops every process listening on the configured ports + orphaned+project processes, waits for file locks to release, then removes build+artefacts and venvs."""from __future__ import annotations@@ -11,10 +19,7 @@ import shutilimport timefrom pathlib import Path-from cli.colors import console-from cli.config import load_config-from cli.platform_ import project_root-from cli.ports import kill_orphaned_machina_processes, kill_port+from cli._common import free_all_ports, preflight# Removed each run -- order doesn't matter, ``shutil.rmtree`` is recursive.@@ -26,19 +31,22 @@ _TARGETS = ["client/node_modules","client/dist","client/.vite",- # Python venvs+ # Python venvs. ``server/.venv`` is uv's default location for the+ # server's standalone project. ``.venv`` at the repo root is a+ # leftover from the brief workspace-layout experiment -- harmless+ # to wipe alongside if present."server/.venv",- ".venv", # stale root venv (should not exist)+ ".venv",]# Children of ``<repo>/.machina/`` to wipe selectively. The bare# ``.machina`` entry can't go in ``_TARGETS`` anymore because the# ``workflows/`` subtree holds shipped example seeds (git-tracked,-# imported on first launch by ``services.example_loader``) — wiping it-# would force the operator to re-clone to recover. Anything else under-# ``.machina/`` (claude state, workspaces, credentials.db, …) is-# transient runtime state and is fair game.+# imported on first launch by ``services.example_loader``) -- wiping+# it would force the operator to re-clone to recover. Anything else+# under ``.machina/`` (claude state, workspaces, credentials.db, ...)+# is transient runtime state and is fair game._MACHINA_KEEP = frozenset({"workflows"})@@ -50,52 +58,69 @@ def _rmtree_with_retry(path: Path, *, attempts: int = 3, delay: float = 0.1) ->return Trueexcept OSError as exc:if attempt == attempts - 1:- console.print(f" [yellow]Warning: Could not remove {path.name}: {exc}[/]")+ print(f" warning: could not remove {path.name}: {exc}")return Falsetime.sleep(delay)return False-def clean_command() -> None:- cfg = load_config()- root = project_root()-- console.print("[bold]Cleaning MachinaOS...[/]\n")+def _kill_running_processes(cfg, root: Path) -> bool:+ """Best-effort: kill anything on configured ports + orphaned project+ processes. Returns True if anything was killed (so the caller knows+ to wait for file locks to release before deleting directories).++ The process-killing path needs ``psutil`` (via :mod:`cli.ports`). If+ it isn't importable -- partially broken env -- we print a warning+ and skip; the directory-removal step still runs.+ """+ try:+ results = free_all_ports(cfg)+ # ``free_all_ports`` itself lazy-imports ``cli.ports`` -- the+ # outer try/except catches the ImportError if psutil is gone.+ from cli.ports import kill_orphaned_machina_processes+ except ImportError as exc:+ print(f" warning: psutil unavailable ({exc.name}); skipping process cleanup")+ return False- # Step 1: kill anything on configured ports- console.print("Stopping running processes...")killed_ports = 0- for port in cfg.all_ports:- result = kill_port(port)+ for port, result in zip(cfg.all_ports, results):if result.killed_pids:- console.print(f" Port {port}: Killed {len(result.killed_pids)} process(es)")+ print(f" port {port}: killed {len(result.killed_pids)} process(es)")killed_ports += len(result.killed_pids)- # Step 2: kill orphaned project processes (may hold .venv file locks).- # ``exclude_substring="-m cli"`` skips the supervisor running this- # very ``clean`` command — its cmdline contains the entry-point- # token ``-m cli``.orphaned = kill_orphaned_machina_processes(str(root), exclude_substring="-m cli")if orphaned:- console.print(f" Orphaned: Killed {len(orphaned)} process(es)")+ print(f" orphaned: killed {len(orphaned)} process(es)")++ return bool(killed_ports or orphaned)+++def clean_command() -> None:+ cfg, root = preflight()++ print("Cleaning MachinaOS...")- if killed_ports or orphaned:- console.print(" Waiting for processes to release file locks...")+ # Step 1+2: kill running processes (best-effort, may degrade)+ print("Stopping running processes...")+ killed_any = _kill_running_processes(cfg, root)+ if killed_any:+ print(" waiting for processes to release file locks...")time.sleep(1.0)else:- console.print(" No running processes found.")+ print(" no running processes found.")- # Step 3: remove directories- console.print("\nRemoving directories...")+ # Step 3: remove top-level artefact directories+ print()+ print("Removing directories...")for target in _TARGETS:path = root / targetif path.exists():- console.print(f" Removing: {target}")+ print(f" removing: {target}")_rmtree_with_retry(path)- # Step 4: selectively clean ``<repo>/.machina/`` — preserve+ # Step 4: selectively clean ``<repo>/.machina/`` -- preserve# ``workflows/`` (shipped example seeds, see ``_MACHINA_KEEP``);- # wipe everything else (claude/, workspaces/, *.db, …) so the+ # wipe everything else (claude/, workspaces/, *.db, ...) so the# repo-local DATA_DIR opt-out gets the same fresh-state treatment.machina_dir = root / ".machina"if machina_dir.is_dir():@@ -103,13 +128,14 @@ def clean_command() -> None:if child.name in _MACHINA_KEEP:continuerel = f".machina/{child.name}"- console.print(f" Removing: {rel}")+ print(f" removing: {rel}")if child.is_dir():_rmtree_with_retry(child)else:try:child.unlink()except OSError as exc:- console.print(f" [yellow]Warning: Could not remove {rel}: {exc}[/]")+ print(f" warning: could not remove {rel}: {exc}")- console.print("\n[green]Done.[/]")+ print()+ print("Done.")diff --git a/cli/commands/daemon.py b/cli/commands/daemon.pydeleted file mode 100644index 610d0017..00000000--- a/cli/commands/daemon.py+++ /dev/null@@ -1,147 +0,0 @@-"""``machina daemon`` -- run the backend as a detached process.--Pure-Python, all-platforms. No NSSM / systemd / launchd integration.-Spawns ``uvicorn main:app`` in a new session (POSIX) or detached-process group (Windows), writes the PID under ``~/.machina/`` so the-other verbs can find it, and uses ``psutil`` for tree-kill on stop.--For boot-time auto-start, configure your OS service manager-separately (`systemctl`, `launchctl`, Task Scheduler) -- this CLI does-not register itself with the system.-"""--from __future__ import annotations--import subprocess-from pathlib import Path--import psutil-import typer--from cli.buildenv import venv_python-from cli.colors import console-from cli.platform_ import IS_WINDOWS, project_root--app = typer.Typer(- name="daemon",- help="Run the MachinaOs backend as a detached process.",- no_args_is_help=True,- add_completion=False,-)---# ---------------------------------------------------------------- helpers--_PID_DIR = Path.home() / ".machina"-_PID_FILE = _PID_DIR / "machina-backend.pid"---def _detached_kwargs() -> dict:- """Cross-platform "spawn detached, survive parent exit" kwargs."""- if IS_WINDOWS:- # CREATE_NEW_PROCESS_GROUP lets us send CTRL_BREAK_EVENT later;- # DETACHED_PROCESS releases the console handle.- return {- "creationflags": (- subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP- ),- }- # POSIX: setsid puts the child in its own process group / session,- # so killing the parent (this CLI) doesn't take the daemon down.- return {"start_new_session": True}---def _read_pid() -> int | None:- if not _PID_FILE.exists():- return None- try:- pid = int(_PID_FILE.read_text().strip())- except (ValueError, OSError):- return None- return pid if psutil.pid_exists(pid) else None---def _kill_tree(pid: int) -> None:- try:- proc = psutil.Process(pid)- except psutil.NoSuchProcess:- return- for child in proc.children(recursive=True):- try:- child.kill()- except psutil.NoSuchProcess:- pass- try:- proc.terminate()- proc.wait(timeout=5)- except psutil.NoSuchProcess:- return- except psutil.TimeoutExpired:- try:- proc.kill()- except psutil.NoSuchProcess:- pass---# ---------------------------------------------------------------- verbs--[email protected]("start")-def start_command() -> None:- """Start the backend in the background; write PID to ~/.machina/."""- if (existing := _read_pid()) is not None:- console.print(f"[yellow]Already running (pid={existing}).[/]")- return-- root = project_root()- server = root / "server"- py = venv_python(root)- if py is None:- console.print(f'[red]Python venv not found at {py}.[/] Run "machina build" first.')- raise typer.Exit(code=1)-- _PID_DIR.mkdir(parents=True, exist_ok=True)- log_file = _PID_DIR / "backend.log"- log = log_file.open("ab")-- proc = subprocess.Popen(- [str(py), "-m", "uvicorn", "main:app",- "--host", "0.0.0.0", "--port", "3010", "--log-level", "warning"],- cwd=str(server),- stdin=subprocess.DEVNULL,- stdout=log,- stderr=log,- **_detached_kwargs(),- )- _PID_FILE.write_text(str(proc.pid))- console.print(f"[green]Started pid={proc.pid}[/] (logs: {log_file})")--[email protected]("stop")-def stop_command() -> None:- """Stop the backend if running; clear PID file."""- pid = _read_pid()- if pid is None:- console.print("Not running.")- _PID_FILE.unlink(missing_ok=True)- return- _kill_tree(pid)- _PID_FILE.unlink(missing_ok=True)- console.print(f"[green]Stopped pid={pid}[/]")--[email protected]("status")-def status_command() -> None:- """Report whether the backend is running."""- pid = _read_pid()- if pid is None:- console.print("Not running.")- raise typer.Exit(code=1)- console.print(f"[green]Running pid={pid}[/]")--[email protected]("restart")-def restart_command() -> None:- """Stop then start; convenience wrapper."""- stop_command()- start_command()diff --git a/cli/commands/daemon/__init__.py b/cli/commands/daemon/__init__.pynew file mode 100644index 00000000..ee295c49--- /dev/null+++ b/cli/commands/daemon/__init__.py@@ -0,0 +1,47 @@+"""``machina daemon`` -- run the backend as a detached process.++Pure-Python, all-platforms. No NSSM / systemd / launchd integration.+Spawns ``uvicorn main:app`` in a new session (POSIX) or detached+process group (Windows), writes the PID under the project's+user-data dir (see :func:`cli.platform_.user_data_dir`), and uses+``psutil`` for tree-kill on stop.++Package layout (verb-per-file, following pdm's ``commands/venv/`` and+hatch's per-verb-folder convention):++ - :mod:`._state` -- ``pid_dir`` / ``pid_file`` / ``read_pid`` /+ ``kill_tree`` / ``detached_kwargs`` (lazy --+ no module-level side effects)+ - :mod:`.start` -- ``daemon start`` verb+ - :mod:`.stop` -- ``daemon stop`` verb+ - :mod:`.status` -- ``daemon status`` verb+ - :mod:`.restart` -- ``daemon restart`` verb++For boot-time auto-start, configure your OS service manager separately+(``systemctl``, ``launchctl``, Task Scheduler) -- this CLI does not+register itself with the system.+"""++from __future__ import annotations++import typer++# The ``app`` Typer instance is declared FIRST so the verb modules can+# import it via ``from . import app`` and register themselves via+# ``@app.command``. The verb-module imports BELOW are what trigger that+# registration -- without them, ``machina daemon`` would be empty.+app = typer.Typer(+ name="daemon",+ help="Run the MachinaOs backend as a detached process.",+ no_args_is_help=True,+ add_completion=False,+)++# Import order matters only for ``restart`` (which imports ``start_command``+# + ``stop_command``); list those two first for clarity, then the rest.+from . import start # noqa: E402,F401+from . import stop # noqa: E402,F401+from . import status # noqa: E402,F401+from . import restart # noqa: E402,F401++__all__ = ["app"]diff --git a/cli/commands/daemon/_state.py b/cli/commands/daemon/_state.pynew file mode 100644index 00000000..6aaa306a--- /dev/null+++ b/cli/commands/daemon/_state.py@@ -0,0 +1,97 @@+"""Shared state for the ``machina daemon`` verbs.++PID-file location, detached-spawn kwargs, and the ``psutil``-backed+tree-kill helper that ``start`` / ``stop`` / ``status`` / ``restart``+all need. Lives in its own module so each verb file imports only what+it uses -- no module-level side effects (the PID-dir resolution+happens inside :func:`pid_dir`, not at import time, so importing this+module is cheap and doesn't depend on ``platformdirs`` being available+until the verb actually runs).+"""++from __future__ import annotations++import subprocess+from pathlib import Path++import psutil++from cli.platform_ import IS_WINDOWS, user_data_dir+++_PID_FILENAME = "machina-backend.pid"+_LOG_FILENAME = "backend.log"+++def pid_dir() -> Path:+ """Project's user-data directory -- created on demand by callers."""+ return user_data_dir()+++def pid_file() -> Path:+ """Path to the daemon's PID file."""+ return pid_dir() / _PID_FILENAME+++def log_file() -> Path:+ """Path to the daemon's stdout/stderr log file."""+ return pid_dir() / _LOG_FILENAME+++def detached_kwargs() -> dict:+ """Cross-platform "spawn detached, survive parent exit" kwargs.++ Windows: ``CREATE_NEW_PROCESS_GROUP`` enables later ``CTRL_BREAK_EVENT``;+ ``DETACHED_PROCESS`` releases the console handle.+ POSIX: ``start_new_session`` puts the child in its own session, so+ killing the parent (this CLI) doesn't take the daemon down.+ """+ if IS_WINDOWS:+ return {+ "creationflags": (+ subprocess.DETACHED_PROCESS | subprocess.CREATE_NEW_PROCESS_GROUP+ ),+ }+ return {"start_new_session": True}+++def read_pid() -> int | None:+ """Return the live PID from the PID file, or ``None`` if absent /+ corrupt / process no longer exists."""+ pf = pid_file()+ if not pf.exists():+ return None+ try:+ pid = int(pf.read_text().strip())+ except (ValueError, OSError):+ return None+ return pid if psutil.pid_exists(pid) else None+++def kill_tree(pid: int) -> None:+ """Terminate ``pid`` and all of its descendants. Best-effort.++ Children are killed first, then the parent is terminated with a+ 5-second grace period; falls back to SIGKILL if the parent doesn't+ exit in time. Matches the supervisor's two-phase shutdown+ semantics.+ """+ try:+ proc = psutil.Process(pid)+ except psutil.NoSuchProcess:+ return+ for child in proc.children(recursive=True):+ try:+ child.kill()+ except psutil.NoSuchProcess:+ pass+ try:+ proc.terminate()+ proc.wait(timeout=5)+ except psutil.NoSuchProcess:+ return+ except psutil.TimeoutExpired:+ try:+ proc.kill()+ except psutil.NoSuchProcess:+ passdiff --git a/cli/commands/daemon/restart.py b/cli/commands/daemon/restart.pynew file mode 100644index 00000000..252ecd4e--- /dev/null+++ b/cli/commands/daemon/restart.py@@ -0,0 +1,14 @@+"""``machina daemon restart`` -- stop then start."""++from __future__ import annotations++from . import app+from .start import start_command+from .stop import stop_command++[email protected]("restart")+def restart_command() -> None:+ """Stop the backend then start it again; convenience wrapper."""+ stop_command()+ start_command()diff --git a/cli/commands/daemon/start.py b/cli/commands/daemon/start.pynew file mode 100644index 00000000..12ed76dd--- /dev/null+++ b/cli/commands/daemon/start.py@@ -0,0 +1,45 @@+"""``machina daemon start`` -- spawn the backend as a detached process."""++from __future__ import annotations++import subprocess++from cli._common import preflight+from cli.colors import console+from cli.platform_ import server_dir+from cli.run import uv_run++from . import app+from ._state import detached_kwargs, log_file, pid_dir, pid_file, read_pid++[email protected]("start")+def start_command() -> None:+ """Start the backend in the background; write PID to the project's+ user-data directory."""+ if (existing := read_pid()) is not None:+ console.print(f"[yellow]Already running (pid={existing}).[/]")+ return++ cfg, root = preflight()+ backend_port = cfg.backend_port++ pid_dir().mkdir(parents=True, exist_ok=True)+ log_path = log_file()+ log = log_path.open("ab")++ proc = subprocess.Popen(+ uv_run(+ "uvicorn", "main:app",+ "--host", "0.0.0.0",+ "--port", str(backend_port),+ "--log-level", "warning",+ ),+ cwd=str(server_dir(root)),+ stdin=subprocess.DEVNULL,+ stdout=log,+ stderr=log,+ **detached_kwargs(),+ )+ pid_file().write_text(str(proc.pid))+ console.print(f"[green]Started pid={proc.pid}[/] (logs: {log_path})")diff --git a/cli/commands/daemon/status.py b/cli/commands/daemon/status.pynew file mode 100644index 00000000..ccbe17e3--- /dev/null+++ b/cli/commands/daemon/status.py@@ -0,0 +1,20 @@+"""``machina daemon status`` -- report whether the backend is running."""++from __future__ import annotations++import typer++from cli.colors import console++from . import app+from ._state import read_pid++[email protected]("status")+def status_command() -> None:+ """Exit 0 if running (and print PID); exit 1 otherwise."""+ pid = read_pid()+ if pid is None:+ console.print("Not running.")+ raise typer.Exit(code=1)+ console.print(f"[green]Running pid={pid}[/]")diff --git a/cli/commands/daemon/stop.py b/cli/commands/daemon/stop.pynew file mode 100644index 00000000..0eb69ff5--- /dev/null+++ b/cli/commands/daemon/stop.py@@ -0,0 +1,22 @@+"""``machina daemon stop`` -- terminate the detached backend."""++from __future__ import annotations++from cli.colors import console++from . import app+from ._state import kill_tree, pid_file, read_pid++[email protected]("stop")+def stop_command() -> None:+ """Stop the backend if running; clear PID file either way."""+ pid = read_pid()+ pf = pid_file()+ if pid is None:+ console.print("Not running.")+ pf.unlink(missing_ok=True)+ return+ kill_tree(pid)+ pf.unlink(missing_ok=True)+ console.print(f"[green]Stopped pid={pid}[/]")diff --git a/cli/commands/dev.py b/cli/commands/dev.pyindex 255cc763..24d64152 100644--- a/cli/commands/dev.py+++ b/cli/commands/dev.py@@ -19,18 +19,21 @@ from pathlib import Pathimport typer+from cli._common import build_backend_spec, free_all_ports, preflightfrom cli.colors import console-from cli.config import load_config-from cli.platform_ import platform_name, project_root+from cli.platform_ import (+ node_modules_dir,+ platform_name,+ static_client_script,+)from cli.buildenv import validate_build-from cli.ports import kill_portfrom cli.supervisor import Manager, ServiceSpecfrom cli.commands._temporal_specs import temporal_specsdef _has_vite(root: Path) -> bool:return (- (root / "node_modules" / "vite").exists()+ (node_modules_dir(root) / "vite").exists()or (root / "client" / "node_modules" / "vite").exists())@@ -47,9 +50,6 @@ def _clear_vite_cache(root: Path) -> None:def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[ServiceSpec]:- static_client = root / "scripts" / "serve-client.js"- server_dir = root / "server"-if use_vite:client_spec = ServiceSpec(name="client",@@ -61,24 +61,13 @@ def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[Servielse:client_spec = ServiceSpec(name="client",- argv=["node", str(static_client)],+ argv=["node", str(static_client_script(root))],cwd=root,ready_port=cfg.client_port,)backend_host = "0.0.0.0" if daemon else "127.0.0.1"- server_spec = ServiceSpec(- name="server",- argv=[- "uv", "run", "uvicorn", "main:app",- "--host", backend_host,- "--port", str(cfg.backend_port),- "--log-level", "warning",- ],- cwd=server_dir,- ready_port=cfg.backend_port,- )-+ server_spec = build_backend_spec(cfg, host=backend_host, root=root)return [client_spec, server_spec, *temporal_specs(root, cfg)]@@ -87,8 +76,7 @@ def dev_command(False, "--daemon", help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",),) -> None:- root = project_root()- cfg = load_config()+ cfg, root = preflight()os.environ.setdefault("PYTHONUTF8", "1")validate_build(root)@@ -99,8 +87,7 @@ def dev_command(console.print(f"Ports: {', '.join(str(p) for p in cfg.all_ports)}")console.log("Freeing ports...")- for port in cfg.all_ports:- kill_port(port)+ free_all_ports(cfg)console.log("Ports ready")_clear_vite_cache(root)diff --git a/cli/commands/docs.py b/cli/commands/docs.pyindex 6749a782..cc160749 100644--- a/cli/commands/docs.py+++ b/cli/commands/docs.py@@ -16,7 +16,7 @@ from pathlib import Pathimport typerfrom cli.colors import console-from cli.platform_ import project_root+from cli.platform_ import project_root, server_dirapp = typer.Typer(@@ -125,7 +125,7 @@ def _rewrite_index(root: Path) -> None:def _check_completeness(root: Path) -> int:documented = _collect_documented_keys(_docs_dir(root))- registered = _collect_registry_keys(root / "server" / "nodes")+ registered = _collect_registry_keys(server_dir(root) / "nodes")missing = sorted(k for k in registered if k not in documented)if not missing:console.print(diff --git a/cli/commands/start.py b/cli/commands/start.pyindex e2e5c23e..e6b3df97 100644--- a/cli/commands/start.py+++ b/cli/commands/start.py@@ -20,11 +20,17 @@ from pathlib import Pathimport typer+from cli._common import build_backend_spec, error_block, free_all_ports, preflightfrom cli.colors import console-from cli.config import load_config-from cli.platform_ import IS_WINDOWS, IS_WSL, platform_name, project_root-from cli.buildenv import validate_build, venv_python-from cli.ports import kill_port+from cli.platform_ import (+ IS_WINDOWS,+ IS_WSL,+ platform_name,+ server_venv,+ static_client_script,+)+from cli.buildenv import validate_build+from cli.run import uv_runfrom cli.supervisor import Manager, ServiceSpecfrom cli.commands._temporal_specs import temporal_specs@@ -37,28 +43,34 @@ def _sqlalchemy_preflight(root: Path) -> None:calls even after exclusions are added. Catching it here gives aclear remediation message instead of letting uvicorn hang silently.See ``docs-internal/errors.md`` #1 / #1a.++ Runs the probe inside the workspace ``.venv`` through ``uv run``+ (via :func:`cli.run.uv_run`) -- same environment the supervised+ services will use, no path-to-interpreter logic on this side."""- py = venv_python(root)- if py is None:- returnstarted = time.monotonic()try:subprocess.run(- [str(py), "-c", "import sqlalchemy"],+ uv_run("python", "-c", "import sqlalchemy"),+ cwd=str(root),timeout=15,check=True,capture_output=True,)except (subprocess.TimeoutExpired, subprocess.CalledProcessError):elapsed = time.monotonic() - started- console.print(f"[red]Error: Python venv health check failed ({elapsed:.1f}s).[/]")- console.print(" sqlalchemy import hung or crashed.")- console.print(" Likely cause: Windows Defender scan cache or stale kernel state.")- console.print(" Fix options:")- console.print(" 1. Restart-Service WinDefend (admin PowerShell)")- console.print(" 2. Reboot the machine")- console.print(f" 3. Add {root / 'server' / '.venv'} to Defender exclusions")- console.print(" See docs-internal/errors.md #1 / #1a for details.")+ error_block(+ f"Python venv health check failed ({elapsed:.1f}s).",+ [+ "sqlalchemy import hung or crashed.",+ "Likely cause: Windows Defender scan cache or stale kernel state.",+ "Fix options:",+ " 1. Restart-Service WinDefend (admin PowerShell)",+ " 2. Reboot the machine",+ f" 3. Add {server_venv(root)} to Defender exclusions",+ "See docs-internal/errors.md #1 / #1a for details.",+ ],+ )raise typer.Exit(code=1)elapsed = time.monotonic() - startedif elapsed > 5.0:@@ -87,33 +99,19 @@ def _read_version(root: Path) -> str:def _build_specs(root: Path, cfg, *, temporal_running: bool) -> list[ServiceSpec]:- static_client = root / "scripts" / "serve-client.js"- server_dir = root / "server"-# Match the existing behaviour: production uses python:start# (bind 127.0.0.1) on Windows/WSL, python:daemon (bind 0.0.0.0)# on POSIX.backend_host = "127.0.0.1" if (IS_WINDOWS or IS_WSL) else "0.0.0.0"- backend_argv = [- "uv", "run", "uvicorn", "main:app",- "--host", backend_host,- "--port", str(cfg.backend_port),- "--log-level", "warning",- ]specs: list[ServiceSpec] = [ServiceSpec(name="client",- argv=["node", str(static_client)],+ argv=["node", str(static_client_script(root))],cwd=root,ready_port=cfg.client_port,),- ServiceSpec(- name="server",- argv=backend_argv,- cwd=server_dir,- ready_port=cfg.backend_port,- ),+ build_backend_spec(cfg, host=backend_host, root=root),]if not temporal_running:specs.extend(temporal_specs(root, cfg))@@ -121,8 +119,7 @@ def _build_specs(root: Path, cfg, *, temporal_running: bool) -> list[ServiceSpecdef start_command() -> None:- root = project_root()- cfg = load_config()+ cfg, root = preflight()os.environ.setdefault("PYTHONUTF8", "1")validate_build(root, require_client_dist=True)@@ -133,8 +130,7 @@ def start_command() -> None:console.print("[dim]Temporal already running, skipping[/]")console.log("Freeing ports...")- for port in cfg.all_ports:- kill_port(port)+ free_all_ports(cfg)console.log("Ports ready")version = _read_version(root)diff --git a/cli/commands/stop.py b/cli/commands/stop.pyindex 8664b921..c4ce18f0 100644--- a/cli/commands/stop.py+++ b/cli/commands/stop.py@@ -11,19 +11,17 @@ import timeimport typer+from cli._common import free_all_ports, preflightfrom cli.colors import console-from cli.config import load_config-from cli.platform_ import platform_name, project_root+from cli.platform_ import platform_namefrom cli.ports import (kill_by_pattern,kill_orphaned_machina_processes,- kill_port,)def stop_command() -> None:- cfg = load_config()- root = project_root()+ cfg, root = preflight()console.print()console.print("[bold]Stopping MachinaOS services...[/]")@@ -33,8 +31,7 @@ def stop_command() -> None:console.print()all_stopped = True- for port in cfg.all_ports:- result = kill_port(port)+ for port, result in zip(cfg.all_ports, free_all_ports(cfg)):status = "[green]\\[OK][/]" if result.port_free else "[red]\\[!!][/]"if result.port_free:if result.killed_pids:diff --git a/cli/platform_.py b/cli/platform_.pyindex e7e6199e..99c265dd 100644--- a/cli/platform_.py+++ b/cli/platform_.py@@ -1,4 +1,29 @@-"""Platform / shell / venv detection helpers."""+"""Platform / shell / venv detection + canonical path-prefix helpers.++All on-disk locations the CLI needs (server tree, the server's uv venv,+client static script, build-output index, OS-native user dirs) are+derived from one prefix -- :func:`project_root` -- via the helpers+below. No callsite composes ``root / "server"`` / ``root / ".venv"``+inline; every consumer imports the named helper. This keeps layout+knowledge centralised so a future repo rename / directory relocation+is a single-file edit.++The CLI is **independent of the server's uv environment**: ``machina``+is installable via pipx / system Python without involving uv, and+shells out to ``uv run --no-sync ...`` (via :func:`cli.run.uv_run`)+for any server-side command. :func:`server_venv` exists so build /+clean / preflight code can check or report that venv's location+without composing it inline.++``server_venv`` respects uv's documented ``UV_PROJECT_ENVIRONMENT``+override (https://docs.astral.sh/uv/concepts/projects/config/) so+power users with non-default venv locations still work.++OS-native user dirs (data, cache, config, log) are derived through+``platformdirs`` (https://pypi.org/project/platformdirs/) -- the same+library the server uses for its pooch binary cache -- so the two halves+of the project agree on per-OS conventions.+"""from __future__ import annotations@@ -30,8 +55,110 @@ def platform_name() -> str:def project_root() -> Path:- """Resolve the project root from a module under ``machina/``.+ """Resolve the project root from a module under ``cli/``.- Layout: ``<project_root>/machina/<this_file>`` -> parents[1].+ Layout: ``<project_root>/cli/<this_file>`` -> parents[1]."""return Path(__file__).resolve().parents[1]+++# ---------------------------------------------------------------------------+# Path-prefix helpers -- canonical layout derived from ``project_root``.+# ---------------------------------------------------------------------------++def _root(root: Path | None) -> Path:+ return root if root is not None else project_root()+++def server_dir(root: Path | None = None) -> Path:+ """The ``server/`` directory -- the Python backend + plugin tree.+ ``server/`` is its own standalone uv project (its ``pyproject.toml``+ declares the dependency closure ``uv sync`` resolves)."""+ return _root(root) / "server"+++def server_venv(root: Path | None = None) -> Path:+ """The server's uv-managed project environment directory.++ ``server/`` is a standalone uv project, so uv places its venv at+ ``server/.venv`` by default per https://docs.astral.sh/uv/concepts/+ projects/layout/. The ``UV_PROJECT_ENVIRONMENT`` env var overrides+ this -- relative overrides resolve against ``server/`` (matching+ uv's own behaviour), absolute paths are used verbatim.++ The CLI itself does NOT live in this venv; ``machina`` is+ independently installable (pipx / system python). This helper+ exists so build / clean / preflight code can check or report the+ server venv's location without anyone composing the path inline.+ """+ base = server_dir(root)+ override = os.environ.get("UV_PROJECT_ENVIRONMENT")+ if override:+ path = Path(override)+ return path if path.is_absolute() else base / path+ return base / ".venv"+++def node_modules_dir(root: Path | None = None) -> Path:+ """The pnpm/npm-installed dependency tree at the workspace root."""+ return _root(root) / "node_modules"+++def client_dist_entry(root: Path | None = None) -> Path:+ """The Vite-built client entrypoint -- proof that the client side+ of ``machina build`` completed."""+ return _root(root) / "client" / "dist" / "index.html"+++def static_client_script(root: Path | None = None) -> Path:+ """The Node.js static-server script that serves the built client+ (used by ``machina start``)."""+ return _root(root) / "scripts" / "serve-client.js"+++# ---------------------------------------------------------------------------+# OS-native user directories via ``platformdirs``+# (https://pypi.org/project/platformdirs/). ``platformdirs`` is imported+# inside each helper, NOT at module level, so the rest of+# ``cli.platform_`` (path-prefix helpers, project_root, the platform+# booleans) keeps loading even when the wheel hasn't been installed+# yet -- the recovery-verb scenario (``machina clean`` against a+# half-broken env). Callers that actually need a user dir trigger the+# import on first call; if missing, the natural ``ModuleNotFoundError``+# surfaces at that callsite, not at every CLI import.+# ---------------------------------------------------------------------------++_APP_NAME = "MachinaOs"+++def user_data_dir() -> Path:+ """User data directory.++ Honours the project's ``DATA_DIR`` env override (see+ ``.env.template``) -- the convention shared with the server's+ ``core.paths.machina_root``. Otherwise delegates to platformdirs.+ """+ override = os.environ.get("DATA_DIR")+ if override:+ return Path(override).expanduser()+ import platformdirs+ return platformdirs.user_data_path(_APP_NAME, appauthor=_APP_NAME)+++def user_cache_dir() -> Path:+ """User cache directory (downloaded binaries / pooch caches).+ Matches ``server/core/paths.py::packages_dir``."""+ import platformdirs+ return platformdirs.user_cache_path(_APP_NAME, appauthor=_APP_NAME)+++def user_config_dir() -> Path:+ """User config directory."""+ import platformdirs+ return platformdirs.user_config_path(_APP_NAME, appauthor=_APP_NAME)+++def user_log_dir() -> Path:+ """User log directory."""+ import platformdirs+ return platformdirs.user_log_path(_APP_NAME, appauthor=_APP_NAME)diff --git a/cli/pyproject.toml b/cli/pyproject.tomldeleted file mode 100644index 1da3f4ed..00000000--- a/cli/pyproject.toml+++ /dev/null@@ -1,32 +0,0 @@-[project]-name = "machina"-version = "0.1.0"-description = "MachinaOS project supervisor CLI"-requires-python = ">=3.11"-dependencies = [- "typer>=0.12",- "rich>=13",- "psutil>=6",- "anyio>=4",- # Required on Windows for the supervisor's Job Object (cli/tree.py).- # Without it, child processes survive abnormal supervisor exit (SIGKILL,- # BSOD, console close) and accumulate as orphans across dev restarts.- # Floor 308 is the first release shipping prebuilt wheels for Python 3.13.- "pywin32>=308; platform_system == 'Windows'",-]--[project.scripts]-machina = "cli.cli:app"--[build-system]-requires = ["setuptools>=68"]-build-backend = "setuptools.build_meta"--[tool.setuptools.packages.find]-where = ["."]-include = ["cli*"]-exclude = ["tests*"]--[tool.pytest.ini_options]-testpaths = ["tests"]-asyncio_mode = "auto"diff --git a/cli/run.py b/cli/run.pyindex f918429e..7ba89feb 100644--- a/cli/run.py+++ b/cli/run.py@@ -40,6 +40,33 @@ def which_argv(argv: list[str]) -> list[str]:return [shutil.which(argv[0]) or argv[0], *argv[1:]]+def uv_run(*args: str) -> list[str]:+ """Standardized argv for executing a command inside the workspace+ ``.venv`` via ``uv run``.++ ``uv run`` is the documented subcommand for executing commands+ against a uv project / workspace environment+ (https://docs.astral.sh/uv/reference/cli/#uv-run). With the workspace+ declared in the repo-root ``pyproject.toml``, ``uv sync`` materialises+ one shared ``.venv`` at the workspace root and installs every member+ (currently ``server/``) editable into it -- so ``python -m+ services.*`` resolves out of that single environment+ (https://docs.astral.sh/uv/concepts/projects/sync/).++ ``--no-sync`` skips the per-invocation lockfile re-check that ``uv+ run`` does by default. ``machina build`` is the single place that+ actually re-syncs; every other entry point (start, dev, daemon,+ supervised runtimes, preflight) trusts the lockfile and just+ activates the env. This is the documented optimisation for hot+ spawn paths (https://docs.astral.sh/uv/reference/cli/#uv-run).++ All ``uv run ...`` invocations in this CLI MUST go through this+ helper -- never inline ``["uv", "run", ...]`` argv lists -- so the+ flags + semantics stay uniform.+ """+ return ["uv", "run", "--no-sync", *args]++def run(argv: list[str],*,diff --git a/cli/tests/test_daemon.py b/cli/tests/test_daemon.pyindex b20a5027..71fdd979 100644--- a/cli/tests/test_daemon.py+++ b/cli/tests/test_daemon.py@@ -1,4 +1,17 @@-"""Smoke tests for ``cli.commands.daemon``."""+"""Smoke tests for ``cli.commands.daemon`` (verb-per-file package).++Post-refactor, the shared helpers live in :mod:`cli.commands.daemon._state`:++ - ``detached_kwargs()`` -- POSIX vs Windows spawn flags+ - ``pid_file()`` / ``pid_dir()`` / ``log_file()`` -- lazy path lookups+ - ``read_pid()`` -- PID-file → live-pid lookup+ - ``kill_tree(pid)`` -- psutil-backed recursive terminate++The verb entry points live in sibling modules (``start.py`` / ``stop.py``+/ ``status.py`` / ``restart.py``). Patches target whichever module+actually owns the attribute under test -- mirrors how pdm tests its+``commands/venv/`` sub-package.+"""from __future__ import annotations@@ -9,72 +22,72 @@ from unittest.mock import MagicMock, patchimport psutilimport pytest-from cli.commands import daemon+from cli.commands.daemon import _state, status, stop-# venv-python discovery is now centralised in cli.buildenv; covered-# by tests/test_start.py (test_venv_python_finds_*).-+# ---------------------------------------------------------------- helpersdef test_detached_kwargs_windows_uses_creationflags():# subprocess.DETACHED_PROCESS and CREATE_NEW_PROCESS_GROUP are only- # defined on Windows. Patching them in with `create=True` lets the- # test cover the Windows branch of `_detached_kwargs` on every CI- # runner (POSIX or Windows) without resorting to a skipif that would- # leave the branch entirely uncovered on the Linux-only CI matrix.+ # defined on Windows. Patching them in with ``create=True`` lets the+ # test cover the Windows branch of ``detached_kwargs`` on every CI+ # runner (POSIX or Windows) without a skipif that would leave the+ # branch entirely uncovered on the Linux-only CI matrix.# Real values from windows.h: DETACHED_PROCESS=0x08, GROUP=0x200.fake_detached = 0x00000008fake_new_group = 0x00000200- with patch.object(daemon, "IS_WINDOWS", True), \+ with patch.object(_state, "IS_WINDOWS", True), \patch.object(subprocess, "DETACHED_PROCESS", fake_detached, create=True), \patch.object(subprocess, "CREATE_NEW_PROCESS_GROUP", fake_new_group, create=True):- kw = daemon._detached_kwargs()+ kw = _state.detached_kwargs()assert "creationflags" in kwassert kw["creationflags"] == fake_detached | fake_new_groupassert "start_new_session" not in kwdef test_detached_kwargs_posix_uses_setsid():- with patch.object(daemon, "IS_WINDOWS", False):- kw = daemon._detached_kwargs()+ with patch.object(_state, "IS_WINDOWS", False):+ kw = _state.detached_kwargs()assert kw == {"start_new_session": True}def test_read_pid_returns_none_when_file_missing(tmp_path: Path):- with patch.object(daemon, "_PID_FILE", tmp_path / "missing.pid"):- assert daemon._read_pid() is None+ with patch.object(_state, "pid_file", return_value=tmp_path / "missing.pid"):+ assert _state.read_pid() is Nonedef test_read_pid_returns_none_for_corrupt_pid_file(tmp_path: Path):- pid_file = tmp_path / "cli.pid"- pid_file.write_text("not-a-number")- with patch.object(daemon, "_PID_FILE", pid_file):- assert daemon._read_pid() is None+ pid_path = tmp_path / "cli.pid"+ pid_path.write_text("not-a-number")+ with patch.object(_state, "pid_file", return_value=pid_path):+ assert _state.read_pid() is Nonedef test_read_pid_returns_none_when_process_no_longer_exists(tmp_path: Path):- pid_file = tmp_path / "cli.pid"- pid_file.write_text("999999")- with patch.object(daemon, "_PID_FILE", pid_file), \- patch.object(daemon.psutil, "pid_exists", return_value=False):- assert daemon._read_pid() is None+ pid_path = tmp_path / "cli.pid"+ pid_path.write_text("999999")+ with patch.object(_state, "pid_file", return_value=pid_path), \+ patch.object(_state.psutil, "pid_exists", return_value=False):+ assert _state.read_pid() is Nonedef test_read_pid_returns_pid_when_alive(tmp_path: Path):- pid_file = tmp_path / "cli.pid"- pid_file.write_text("1234\n")- with patch.object(daemon, "_PID_FILE", pid_file), \- patch.object(daemon.psutil, "pid_exists", return_value=True):- assert daemon._read_pid() == 1234+ pid_path = tmp_path / "cli.pid"+ pid_path.write_text("1234\n")+ with patch.object(_state, "pid_file", return_value=pid_path), \+ patch.object(_state.psutil, "pid_exists", return_value=True):+ assert _state.read_pid() == 1234++# ---------------------------------------------------------------- kill_treedef test_kill_tree_terminates_children_and_parent():parent = MagicMock()child1 = MagicMock()child2 = MagicMock()parent.children.return_value = [child1, child2]- with patch.object(daemon.psutil, "Process", return_value=parent):- daemon._kill_tree(123)+ with patch.object(_state.psutil, "Process", return_value=parent):+ _state.kill_tree(123)child1.kill.assert_called_once()child2.kill.assert_called_once()parent.terminate.assert_called_once()@@ -85,29 +98,36 @@ def test_kill_tree_force_kills_on_timeout():parent = MagicMock()parent.children.return_value = []parent.wait.side_effect = psutil.TimeoutExpired(seconds=5)- with patch.object(daemon.psutil, "Process", return_value=parent):- daemon._kill_tree(123)+ with patch.object(_state.psutil, "Process", return_value=parent):+ _state.kill_tree(123)parent.terminate.assert_called_once()parent.kill.assert_called_once()def test_kill_tree_no_such_process_is_noop():- with patch.object(daemon.psutil, "Process", side_effect=psutil.NoSuchProcess(123)):- daemon._kill_tree(123)+ with patch.object(_state.psutil, "Process", side_effect=psutil.NoSuchProcess(123)):+ _state.kill_tree(123)++# ---------------------------------------------------------------- verbsdef test_stop_command_clears_pid_file_when_not_running(tmp_path: Path):- pid_file = tmp_path / "cli.pid"- pid_file.write_text("999999")- with patch.object(daemon, "_PID_FILE", pid_file), \- patch.object(daemon, "_read_pid", return_value=None):- daemon.stop_command()- assert not pid_file.exists()+ # ``stop`` module imports ``pid_file`` / ``read_pid`` by name from+ # ``_state``, so the patches must target the consumer's namespace+ # (``stop.pid_file``), not the source module (``_state.pid_file``).+ # Classic "where to patch" gotcha -- see+ # https://docs.python.org/3/library/unittest.mock.html#where-to-patch.+ pid_path = tmp_path / "cli.pid"+ pid_path.write_text("999999")+ with patch.object(stop, "pid_file", return_value=pid_path), \+ patch.object(stop, "read_pid", return_value=None):+ stop.stop_command()+ assert not pid_path.exists()def test_status_command_exits_1_when_not_running():import typer- with patch.object(daemon, "_read_pid", return_value=None), \+ with patch.object(status, "read_pid", return_value=None), \pytest.raises(typer.Exit) as exc:- daemon.status_command()+ status.status_command()assert exc.value.exit_code == 1diff --git a/cli/tests/test_start.py b/cli/tests/test_start.pyindex 746d2232..373bb3e0 100644--- a/cli/tests/test_start.py+++ b/cli/tests/test_start.py@@ -5,7 +5,6 @@ from __future__ import annotationsfrom pathlib import Pathfrom unittest.mock import patch-from cli import buildenvfrom cli.commands import startfrom cli.config import Config, load_config@@ -18,22 +17,12 @@ def _cfg() -> Config:return load_config()-def test_venv_python_returns_none_when_missing(tmp_path: Path):- assert buildenv.venv_python(tmp_path) is None---def test_venv_python_finds_windows_layout(tmp_path: Path):- win_py = tmp_path / "server" / ".venv" / "Scripts" / "python.exe"- win_py.parent.mkdir(parents=True)- win_py.write_text("")- assert buildenv.venv_python(tmp_path) == win_py---def test_venv_python_finds_posix_layout(tmp_path: Path):- posix_py = tmp_path / "server" / ".venv" / "bin" / "python"- posix_py.parent.mkdir(parents=True)- posix_py.write_text("")- assert buildenv.venv_python(tmp_path) == posix_py+# The previous ``test_venv_python_*`` cases verified a custom helper+# that walked ``server/.venv/{Scripts,bin}`` paths. That helper has been+# retired: subprocess launchers now build their argv via+# :func:`cli.run.uv_run`, which delegates interpreter selection to+# ``uv run`` (https://docs.astral.sh/uv/reference/cli/#uv-run). Nothing+# platform-specific to assert from the CLI side anymore.def test_temporal_running_false_when_port_closed():diff --git a/pyproject.toml b/pyproject.tomlindex e05c0bea..5d20a98d 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -8,6 +8,13 @@ dependencies = ["rich>=13","anyio>=4","psutil>=6",+ # OS-native user data / cache / config / log dirs. Soft dependency+ # in the CLI (``cli/platform_.py`` imports it inside a try/except+ # and falls back to a stdlib implementation if the wheel isn't+ # available) so ``machina clean`` / ``machina build`` still work+ # immediately after a wipe, before ``pip install`` has had a+ # chance to materialise it.+ "platformdirs>=4.0",# Required on Windows for the supervisor's Job Object (cli/tree.py).# Without it, child processes survive abnormal supervisor exit# (SIGKILL, BSOD, console close) and accumulate as orphans across@@ -25,3 +32,17 @@ build-backend = "hatchling.build"[tool.hatch.build.targets.wheel]packages = ["cli"]++[dependency-groups]+dev = []++# ``machinaos-cli`` is a standalone Python CLI package -- installable+# via ``pipx install .`` / ``pip install .`` against any Python >=3.12+# without involving uv. It depends on nothing from ``server/``. The+# server has its own uv-managed venv at ``server/.venv``; the CLI+# invokes server-side commands by shelling out via ``cli.run.uv_run``+# (which runs ``uv run --no-sync ...`` with ``cwd=server/`` so uv+# discovers ``server/pyproject.toml`` and activates ``server/.venv``).+# Keeping the CLI independent of the uv workspace means contributors+# can install / run / debug ``machina`` on whatever interpreter is on+# PATH -- no per-checkout venv activation required.diff --git a/cli/commands/_supervised_runtime.py b/server/services/temporal/_supervised_runtime.pysimilarity index 73%rename from cli/commands/_supervised_runtime.pyrename to server/services/temporal/_supervised_runtime.pyindex d5316f2c..b660da41 100644--- a/cli/commands/_supervised_runtime.py+++ b/server/services/temporal/_supervised_runtime.py@@ -1,9 +1,9 @@"""Generic bridge: run any ``BaseSupervisor`` singleton from a CLI.-The Manager supervisor in ``machina/supervisor.py`` schedules+The CLI's ``Manager`` supervisor (``cli/supervisor.py``) schedules``ServiceSpec`` entries by spawning a subprocess and supervising it.``BaseSupervisor``-managed runtimes (pgserver, Temporal binary) don't-ship a CLI of their own — they're Python singletons started via+ship a CLI of their own -- they're Python singletons started via``await runtime.start()``.This shim bridges the two: import a runtime factory by dotted path,@@ -11,12 +11,19 @@ call it, ``await singleton.start()``, then block on a shutdown signal.``Manager`` sends SIGTERM during graceful shutdown; we catch it,``await singleton.stop()``, then exit cleanly.-Usage (inside ``ServiceSpec.argv``):+Module location: this lives inside the ``server`` package because the+factory targets it resolves (``services.temporal._runtime:get_postgres+_runtime`` etc.) are server-side singletons. Hosting the shim here+keeps the CLI free of server-side imports and lets a single ``uv run+python -m services.temporal._supervised_runtime <factory>`` invocation+work against the workspace ``.venv`` -- no PYTHONPATH composition, no+cross-venv plumbing.- [- "python", "-m", "cli.commands._supervised_runtime",- "services.temporal._runtime:get_postgres_runtime",- ]+Invocation (inside ``ServiceSpec.argv``, built via ``cli.run.uv_run``):++ uv_run("python", "-m",+ "services.temporal._supervised_runtime",+ "services.temporal._runtime:get_postgres_runtime")Equivalent to (Python idiom):@@ -62,7 +69,7 @@ async def _run(factory_dotted: str) -> int:except NotImplementedError:# Windows: add_signal_handler raises for SIGTERM. The# Manager supervisor's tree-kill semantics (psutil-based)- # work regardless — we just lose the graceful path on Win.+ # work regardless -- we just lose the graceful path on Win.passprint(f"[supervised_runtime] starting {factory_dotted}", flush=True)@@ -79,7 +86,7 @@ async def _run(factory_dotted: str) -> int:def main() -> int:if len(sys.argv) != 2:print(- "usage: python -m cli.commands._supervised_runtime "+ "usage: python -m services.temporal._supervised_runtime ""<module.path:factory>",file=sys.stderr,)