manta-node 0.6b5.dev697__py3-none-any.whl → 0.6b5.dev702__py3-none-any.whl

manta_node/cli/_version_generated.py

@@ -4,7 +4,7 @@ This file is auto-generated at build time by scripts/generate_version.py.
 Do not edit manually.
 """
 
-__version__ = "2026.09.22.8a098e97"
-__build_date__ = "2026.09.22"
-__commit_id__ = "8a098e97"
+__version__ = "2026.09.24.10597326"
+__build_date__ = "2026.09.24"
+__commit_id__ = "10597326"
 __package_version__ = "0.6b5"

manta_node/cli/commands/status.py

@@ -2,88 +2,64 @@
 
 import argparse
 import contextlib
-import json
-import os
 from datetime import datetime
-from pathlib import Path
 
 import psutil
 from rich.console import Console
 from rich.table import Table
 
+from ...supervisor.records import list_instances
+
 console = Console()
 
 
 def find_running_instances():
-    """Find running node instances by looking for instance JSON files."""
+    """Running instances for display, with the supervisor record read-through.
 
-    instances_dir = Path.home() / ".manta" / "nodes" / "instances"
+    Under a supervisor the pid of record is the supervisor's, and only the
+    supervisor record exists (the child runs with ``--subprocess``); without one
+    it is the node's own instance record. ``list_instances`` resolves both.
+    """
     instances = []
-
-    if not instances_dir.exists():
-        return instances
-
-    for instance_file in instances_dir.glob("*.json"):
+    for record in list_instances():
+        pid = record["pid"]
+        # The workload is the child under a supervisor, the node itself without
+        # one: `status` shows its cpu/memory, while `pid` stays the pid a stop
+        # signals (the supervisor's, when present).
+        workload_pid = record.get("workload_pid") or pid
+        cpu_percent = None
+        memory_mb = None
+        create_time = None
+        status = "running"
         try:
-            with open(instance_file, "r") as f:
-                instance_data = json.load(f)
-
-            pid = instance_data.get("pid")
-            instance_id = instance_data.get("instance_id", instance_file.stem)
-
-            # Check if process is still running
-            try:
-                # Send signal 0 to check if process exists
-
-                os.kill(pid, 0)
-
-                # Get process info if psutil is available
-                try:
-                    process = psutil.Process(pid)
-                    cpu_percent = process.cpu_percent()
-                    memory_mb = process.memory_info().rss // (1024 * 1024)
-                    create_time = datetime.fromtimestamp(process.create_time())
-                    status = "running"
-                except ImportError:
-                    cpu_percent = None
-                    memory_mb = None
-                    create_time = None
-                    status = "running"
-                except psutil.NoSuchProcess:
-                    # Process disappeared
-                    instance_file.unlink(missing_ok=True)
-                    continue
-
-                # Add additional info from JSON
-                alias = instance_data.get("alias", instance_id)
-                config_name = instance_data.get("config_name", "unknown")
-                start_time_str = instance_data.get("start_time")
-                if start_time_str and not create_time:
-                    with contextlib.suppress(ValueError, TypeError):
-                        create_time = datetime.fromisoformat(start_time_str)
-
-                instances.append(
-                    {
-                        "instance_id": instance_id,
-                        "alias": alias,
-                        "config_name": config_name,
-                        "pid": pid,
-                        "status": status,
-                        "cpu_percent": cpu_percent,
-                        "memory_mb": memory_mb,
-                        "start_time": create_time,
-                        "instance_file": instance_file,
-                    }
-                )
-
-            except OSError:
-                # Process no longer exists, remove stale instance file
-                instance_file.unlink(missing_ok=True)
-
-        except (ValueError, FileNotFoundError):
-            # Invalid instance file, remove it
-            instance_file.unlink(missing_ok=True)
-
+            process = psutil.Process(workload_pid)
+            cpu_percent = process.cpu_percent()
+            memory_mb = process.memory_info().rss // (1024 * 1024)
+            create_time = datetime.fromtimestamp(process.create_time())
+        except ImportError:
+            pass
+        except psutil.NoSuchProcess:
+            # Disappeared between the liveness check and here; skip it.
+            continue
+
+        start_time_str = record.get("start_time")
+        if start_time_str and not create_time:
+            with contextlib.suppress(ValueError, TypeError):
+                create_time = datetime.fromisoformat(start_time_str)
+
+        instances.append(
+            {
+                "instance_id": record["instance_id"],
+                "alias": record["alias"],
+                "config_name": record["config_name"],
+                "pid": pid,
+                "status": status,
+                "cpu_percent": cpu_percent,
+                "memory_mb": memory_mb,
+                "start_time": create_time,
+                "instance_file": record["instance_file"],
+            }
+        )
     return instances
 
 

manta_node/cli/commands/stop.py

@@ -1,14 +1,14 @@
 """Node stop command implementation."""
 
 import argparse
-import json
 import os
 import signal
 import time
-from pathlib import Path
 
 from rich.console import Console
 
+from ...supervisor.records import list_instances
+
 console = Console()
 
 
@@ -28,45 +28,23 @@ def print_warning(message: str):
 
 
 def find_running_instances():
-    """Find running node instances by looking for instance JSON files."""
-
-    instances_dir = Path.home() / ".manta" / "nodes" / "instances"
-    instances = []
-
-    if not instances_dir.exists():
-        return instances
-
-    for instance_file in instances_dir.glob("*.json"):
-        try:
-            with open(instance_file, "r") as f:
-                instance_data = json.load(f)
-
-            pid = instance_data.get("pid")
-            instance_id = instance_data.get("instance_id", instance_file.stem)
-            alias = instance_data.get("alias", instance_id)
-
-            # Check if process is still running
-            try:
-                # Send signal 0 to check if process exists
-
-                os.kill(pid, 0)
-                instances.append(
-                    {
-                        "instance_id": instance_id,
-                        "alias": alias,
-                        "pid": pid,
-                        "instance_file": instance_file,
-                    }
-                )
-            except OSError:
-                # Process no longer exists, remove stale instance file
-                instance_file.unlink(missing_ok=True)
-
-        except (ValueError, FileNotFoundError):
-            # Invalid instance file, remove it
-            instance_file.unlink(missing_ok=True)
+    """Running instances to stop, with the supervisor record read-through.
 
-    return instances
+    The pid returned for each alias is the **pid of record**: the supervisor's
+    when one is present, else the node's own. Signalling it stops the supervisor
+    (which winds the child down) or the node directly — never both.
+    """
+    return [
+        {
+            "instance_id": record["instance_id"],
+            "alias": record["alias"],
+            "pid": record["pid"],
+            "child_pid": record.get("child_pid"),
+            "source": record["source"],
+            "instance_file": record["instance_file"],
+        }
+        for record in list_instances()
+    ]
 
 
 def stop_instance_by_pid(
@@ -85,15 +63,53 @@ def stop_instance_by_pid(
     pid = instance["pid"]
     instance_id = instance["instance_id"]
     alias = instance.get("alias", instance_id)
+    # A supervised node's pid of record is the SUPERVISOR, and its child leads a
+    # SEPARATE process group (`start_new_session=True`), so `killpg` on the
+    # supervisor never reaches the child. A bare SIGKILL of the supervisor cannot
+    # be forwarded and would orphan the child. So: SIGTERM the supervisor, which
+    # forwards to the child and exits; to force, also SIGKILL the recorded child
+    # pid, then the supervisor.
+    owned_by_supervisor = instance.get("source") == "supervisor"
+    child_pid = instance.get("child_pid")
+
+    def signal_supervisor(signum: int) -> None:
+        _signal_pid(pid, signum)
+
+    def signal_child(signum: int) -> None:
+        # The child is its own session: signal the group it leads, so any task
+        # grandchildren it spawned go too. Fall back to the pid if the group is
+        # gone or not ours.
+        if not child_pid:
+            return
+        try:
+            os.killpg(os.getpgid(child_pid), signum)
+        except (ProcessLookupError, PermissionError):
+            _signal_pid(child_pid, signum)
+
+    def _signal_pid(target: int | None, signum: int) -> None:
+        if not target:
+            return
+        try:
+            os.kill(target, signum)
+        except ProcessLookupError:
+            pass
 
     try:
         if force:
-            # Force kill with SIGKILL
-            os.kill(pid, signal.SIGKILL)
+            if owned_by_supervisor:
+                # Force: SIGTERM the supervisor (it forwards and exits), then
+                # SIGKILL the child directly and the supervisor — neither can be
+                # orphaned. A plain SIGKILL of the supervisor alone would orphan
+                # the child, which leads its own session.
+                signal_supervisor(signal.SIGTERM)
+                signal_child(signal.SIGKILL)
+                signal_supervisor(signal.SIGKILL)
+            else:
+                _signal_pid(pid, signal.SIGKILL)
             console.print(f"Force killed node '{alias}' (PID: {pid})")
         else:
             # Graceful shutdown with SIGTERM
-            os.kill(pid, signal.SIGTERM)
+            signal_supervisor(signal.SIGTERM)
             console.print(f"Sent termination signal to node '{alias}' (PID: {pid})")
 
             # Wait for process to terminate gracefully
@@ -111,21 +127,26 @@ def stop_instance_by_pid(
                     console.print(f"[green]Node '{alias}' stopped gracefully[/green]")
                     break
             else:
-                # Timeout reached, process still running
+                # Timeout reached: force the child and the supervisor, never the
+                # supervisor alone (which would orphan the child).
                 print_warning(
                     f"Node '{alias}' did not stop gracefully, sending SIGKILL..."
                 )
-                os.kill(pid, signal.SIGKILL)
+                signal_child(signal.SIGKILL)
+                signal_supervisor(signal.SIGKILL)
                 console.print(f"Force killed node '{alias}' after timeout")
 
-        # Remove instance file
-        instance["instance_file"].unlink(missing_ok=True)
+        # Only the node's own instance record is the CLI's to remove; a
+        # supervisor record is cleared by the supervisor as it exits.
+        if not owned_by_supervisor:
+            instance["instance_file"].unlink(missing_ok=True)
         return True
 
     except OSError as e:
         if e.errno == 3:  # No such process
             # Process already dead, just remove instance file
-            instance["instance_file"].unlink(missing_ok=True)
+            if not owned_by_supervisor:
+                instance["instance_file"].unlink(missing_ok=True)
             print_warning(f"Node '{alias}' was already stopped")
             return True
         else:

manta_node/infrastructure/mqtt/command_handler.py

@@ -23,6 +23,12 @@ from manta_common.errors import (
 from manta_common.retry import RetryPolicy
 from manta_common.traces import Tracer
 
+from ...seam import (
+    SeamClient,
+    SeamError,
+    SwitchOutcome,
+    UpdateRequest,
+)
 from ...task_manager import LOG_FLUSH_INTERVAL, LogStream, TaskManager
 from ...tasks import TaskProgression
 from ..filesystem.dataset_manager import DatasetManager
@@ -128,8 +134,13 @@ class CommandHandler(Collector, MqttBase):
         ping_interval: int = TIMEOUT,
         max_concurrent_tasks: int = 2,
         task_timeout: int = 3600,
+        seam_client: SeamClient | None = None,
     ) -> None:
         self.tracer = Tracer(getLogger(__name__))
+        # The local seam to a supervisor, when one owns this node (2b). None on a
+        # node running without a supervisor: the relay is inert, and the handler
+        # behaves exactly as before (2b acceptance: unused ⇒ no change).
+        self._seam_client = seam_client
         self._task_manager = task_runner
         self.node_client = node_client
         self.dataset_manager = dataset_manager
@@ -669,6 +680,24 @@ class CommandHandler(Collector, MqttBase):
         """
         await self.stop_callback()
 
+    async def relay_update(self, request: UpdateRequest) -> SwitchOutcome | None:
+        """Relay an update request to the supervisor over the seam (2b).
+
+        The node is a **relay**: it holds the control channel and passes the
+        declaration to the supervisor, which executes. With no seam client (a
+        node running without a supervisor) this is inert and returns None — no
+        behaviour change. If the seam is unreachable, the failure is reported and
+        nothing is mutated (NF-3): the node does not fall back to an in-place
+        install.
+        """
+        if self._seam_client is None:
+            return None
+        try:
+            return await self._seam_client.request_update(request)
+        except SeamError as exc:
+            self.tracer.exception(f"Seam relay failed: {exc}")
+            raise MantaNodeError(f"Supervisor seam unavailable: {exc}") from exc
+
     async def on_task_setup_failed(self, task: MqttTask, exc: Exception):
         """
         Publish a FAILED task update when task setup fails.

manta_node/seam.py

@@ -0,0 +1,139 @@
+"""The local seam — the port between the running node and its supervisor.
+
+The seam is the node/domain's **port** (mechanism §6.4): the request/outcome
+interface the running node calls to ask its supervisor to act. The supervisor
+**implements** it with a Unix-socket adapter (`manta_node/supervisor/seam.py`).
+Only the node calls; nothing off-host reaches the supervisor directly.
+
+This module is deliberately **dependency-free** (stdlib only, no `manta_node` or
+`manta_common` import): it is the shared interface, and the supervisor imports it
+without taking on any domain logic — the guard in
+`tests/test_supervisor_is_infrastructure.py` carves it out for exactly that
+reason. Keeping it total (messages and the abstract client) means both sides can
+depend on it without a cycle.
+
+**Contract** (mechanism §6.4). The request carries `request_id` (idempotency),
+the `target` (a pair or set id — the node computes no ordering), `force`, and the
+`declared_sequence` the Manager passed through. The supervisor answers with a
+`state` and a `reason`. The switch restarts the child, so the outcome across a
+switch is observed **asynchronously** after the node comes back (NF-8); the seam
+carries initiation synchronously and the immediate outcome.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Protocol, runtime_checkable
+
+# The socket lives in the node's state dir, never the version tree (NF-6), with
+# 0600 on the socket and its parent. It is local and same-user only (NF-9/NF-10).
+SEAM_SOCKET_NAME = "supervisor.sock"
+
+
+def seam_socket_path() -> Path:
+    """The Unix-socket path for the seam (in the node's state directory)."""
+    return Path.home() / ".manta" / SEAM_SOCKET_NAME
+
+
+class SeamState(str, Enum):
+    """The states the supervisor answers with (mechanism §6.4)."""
+
+    REQUESTED = "requested"
+    REFUSED = "refused"
+    FETCHING = "fetching"
+    VERIFYING = "verifying"
+    STAGED = "staged"
+    SWITCHING = "switching"
+    RESTARTING = "restarting"
+    REVERTING = "reverting"
+    REPORTING = "reporting"
+    REVERTED = "reverted"
+    FAILED = "failed"
+    DOWN = "down"
+
+
+@dataclass(frozen=True)
+class UpdateRequest:
+    """A request from the running node to its supervisor.
+
+    ``target`` is the pair (or a set id that resolves to one); the node computes
+    no ordering, it passes the declaration through. ``declared_sequence`` is the
+    Manager's order, opaque here. ``request_id`` de-duplicates: a repeat of a
+    request already in flight or completed is a no-op (NF-5).
+    """
+
+    request_id: str
+    target: str
+    force: bool = False
+    declared_sequence: int | None = None
+
+    def to_bytes(self) -> bytes:
+        return json.dumps(
+            {
+                "request_id": self.request_id,
+                "target": self.target,
+                "force": self.force,
+                "declared_sequence": self.declared_sequence,
+            }
+        ).encode()
+
+    @classmethod
+    def from_bytes(cls, raw: bytes) -> UpdateRequest:
+        data = json.loads(raw)
+        return cls(
+            request_id=data["request_id"],
+            target=data["target"],
+            force=bool(data.get("force", False)),
+            declared_sequence=data.get("declared_sequence"),
+        )
+
+
+@dataclass(frozen=True)
+class SwitchOutcome:
+    """The supervisor's answer to a request: a state and a reason."""
+
+    request_id: str
+    state: SeamState
+    reason: str = ""
+    detail: dict = field(default_factory=dict)
+
+    def to_bytes(self) -> bytes:
+        return json.dumps(
+            {
+                "request_id": self.request_id,
+                "state": self.state.value,
+                "reason": self.reason,
+                "detail": self.detail,
+            }
+        ).encode()
+
+    @classmethod
+    def from_bytes(cls, raw: bytes) -> SwitchOutcome:
+        data = json.loads(raw)
+        return cls(
+            request_id=data["request_id"],
+            state=SeamState(data["state"]),
+            reason=data.get("reason", ""),
+            detail=data.get("detail", {}),
+        )
+
+
+class SeamError(Exception):
+    """The seam could not carry the request (unreachable, malformed, refused)."""
+
+
+@runtime_checkable
+class SeamClient(Protocol):
+    """The port the running node calls. Implemented by the socket adapter."""
+
+    async def request_update(self, request: UpdateRequest) -> SwitchOutcome:
+        """Carry a request to the supervisor and return its immediate outcome.
+
+        Raises ``SeamError`` if the seam is unreachable: the node reports the
+        failure and mutates nothing (NF-3); it does not fall back to an in-place
+        install.
+        """
+        ...

manta_node/supervisor/__init__.py

@@ -0,0 +1,11 @@
+"""The node supervisor — infrastructure that owns the node child (ADR-0041 B1).
+
+The supervisor is a long-lived process that starts ``manta_node start <alias>``
+as its child and owns the child's restart. It is **infrastructure, not domain**:
+it makes no decision about versions, drift, fleets or outcomes, and it imports
+nothing domain-related from ``manta_node`` (pinned by a guard test). Making a
+version current, verifying a candidate and rolling back are later steps (2c/2d);
+this package is the process manager only.
+"""
+
+__all__ = []

manta_node/supervisor/process.py

@@ -0,0 +1,210 @@
+"""The supervisor process manager — starts the node child and owns its restart.
+
+The systemd unit's ``ExecStart`` becomes ``manta-supervisor <alias>``; the
+supervisor starts ``manta_node start <alias>`` as its child, records itself as the
+pid of record, restarts the child under a **bounded** policy, and treats a stop
+signal as **terminal**. Two restart owners never coexist: the unit restarts only
+the supervisor, the supervisor restarts only the child.
+
+Spike A (manta-node-python#483) proved the shape this implements; the prototype
+is manta-node-python#484. The guarantee that a supervisor killed outright leaves
+no orphan is the unit's ``KillMode=control-group`` (systemd reaps the cgroup);
+``start_new_session=True`` below is the belt-and-braces process-group path for a
+supervisor stopped outside systemd.
+
+**Placement.** At 2a the supervisor runs from the node's own venv, because the
+child's interpreter *is* the supervisor's there. The migration's "supervisor
+installed outside the node venv" is satisfied at 2c, when the child runs from the
+version tree; ``--python`` (``child_python``) selects that interpreter, so the
+supervisor can then live in its own venv without running the node code from the
+wrong one.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import signal
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+from .records import (
+    supervisor_record,
+    supervisor_record_path,
+    write_json_atomic,
+)
+
+# A child that exits more than RESTART_LIMIT times within RESTART_WINDOW_SECONDS
+# is a crash loop: the supervisor stops restarting and exits non-zero, so systemd
+# sees a failed unit rather than an infinitely restarting one.
+RESTART_LIMIT = 5
+RESTART_WINDOW_SECONDS = 120
+RESTART_BACKOFF_SECONDS = 2
+
+# Bound on the supervisor's stdout stream. A long-lived supervisor reopens this
+# on every restart, so without a cap a crash loop grows it without limit.
+STDOUT_MAX_BYTES = 10 * 1024 * 1024
+
+# How long a terminal stop waits for the child to wind down before SIGKILL.
+STOP_GRACE_SECONDS = 10
+
+
+def _log_dir() -> Path:
+    return Path.home() / ".manta" / "logs" / "nodes"
+
+
+class Supervisor:
+    """Runs one node child, restarts it (bounded), and stops it terminally."""
+
+    def __init__(
+        self, alias: str, config: str, child_python: str | None = None
+    ) -> None:
+        self.alias = alias
+        self.config = config
+        # The interpreter that runs the child. Today the supervisor and the node
+        # code share one venv, so this defaults to the supervisor's own; at 2c
+        # the child runs from the version tree's interpreter, a DIFFERENT venv
+        # from the supervisor's, and the unit passes that interpreter here.
+        self.child_python = child_python or sys.executable
+        self._stop = False
+        self._child: subprocess.Popen | None = None
+        self._restarts: list[float] = []
+
+    def _write_record(self, child_pid: int | None, state: str) -> None:
+        write_json_atomic(
+            supervisor_record_path(self.alias),
+            supervisor_record(self.alias, os.getpid(), child_pid, state),
+        )
+
+    def _signal_child(self, signum: int) -> None:
+        """Signal the child's process group, falling back to the child alone.
+
+        The child is spawned with ``start_new_session=True``, so it leads its own
+        group; signalling the group takes any grandchildren with it.
+        """
+        if not self._child or self._child.poll() is not None:
+            return
+        try:
+            os.killpg(os.getpgid(self._child.pid), signum)
+        except (ProcessLookupError, PermissionError):
+            self._child.send_signal(signum)
+
+    def _on_signal(self, signum: int, _frame) -> None:
+        # A stop is terminal: remember it and forward it. The main loop must not
+        # restart once this is set.
+        self._stop = True
+        self._signal_child(signal.SIGTERM)
+
+    def _spawn(self) -> subprocess.Popen:
+        # `--subprocess` is the existing hidden flag: the child does not write an
+        # instance file, so exactly one writer (the supervisor) owns the records.
+        # `--foreground` keeps it attached to this process rather than detaching.
+        # `--alias` is passed explicitly: `--config` names the TOML to load, and
+        # the alias the operator sees must be the supervisor's, not whatever
+        # `identity.alias` the TOML happens to carry.
+        cmd = [
+            self.child_python,
+            "-m",
+            "manta_node",
+            "start",
+            self.config,
+            "--foreground",
+            "--subprocess",
+            "--alias",
+            self.alias,
+        ]
+        log_dir = _log_dir()
+        log_dir.mkdir(parents=True, exist_ok=True)
+        # One writer per path: the supervisor owns the child's stdout/stderr
+        # stream. The child's own rotating file log is separate and untouched.
+        # A long-lived supervisor reopens this on every restart, so it is bounded
+        # like the child's own rotating handler: roll once past the cap, keeping
+        # one previous run. Roll BEFORE the open, and never while a writer holds
+        # it — a rename does not retarget an already-open fd.
+        stdout_path = log_dir / f"{self.alias}.supervisor.stdout"
+        if stdout_path.exists() and stdout_path.stat().st_size >= STDOUT_MAX_BYTES:
+            stdout_path.replace(stdout_path.with_name(f"{stdout_path.name}.1"))
+        with open(stdout_path, "a") as stream:
+            child = subprocess.Popen(
+                cmd, stdout=stream, stderr=stream, start_new_session=True
+            )
+        # Publish the pid BEFORE returning: a signal that fires between here and
+        # the caller's `_stop` check must be able to reach the child, not a gone
+        # one.
+        self._child = child
+        return child
+
+    def run(self) -> int:
+        signal.signal(signal.SIGTERM, self._on_signal)
+        signal.signal(signal.SIGINT, self._on_signal)
+        self._write_record(None, "starting")
+
+        while not self._stop:
+            # `_spawn` publishes `self._child` before returning, so a signal
+            # during the fork reaches the new pid; one arriving just after is
+            # caught by the `_stop` re-check below.
+            child = self._spawn()
+            if self._stop:
+                # A stop arrived while we forked: forward it and do not restart.
+                # Without this the loop would block on a child never signalled.
+                self._signal_child(signal.SIGTERM)
+            self._write_record(child.pid, "running")
+            child.wait()
+            rc = child.returncode
+
+            if self._stop:
+                break
+
+            now = time.monotonic()
+            self._restarts = [
+                t for t in self._restarts if now - t < RESTART_WINDOW_SECONDS
+            ]
+            self._restarts.append(now)
+            if len(self._restarts) > RESTART_LIMIT:
+                self._write_record(None, "crash-loop")
+                print(
+                    f"supervisor: child exited {len(self._restarts)} times in "
+                    f"{RESTART_WINDOW_SECONDS}s (rc={rc}); refusing to restart",
+                    file=sys.stderr,
+                )
+                return 1
+
+            self._write_record(None, "restarting")
+            time.sleep(RESTART_BACKOFF_SECONDS)
+
+        # Terminal stop: wind the child down, then clear our record so `status`
+        # does not report a dead supervisor.
+        if self._child and self._child.poll() is None:
+            self._signal_child(signal.SIGTERM)
+            try:
+                self._child.wait(timeout=STOP_GRACE_SECONDS)
+            except subprocess.TimeoutExpired:
+                self._signal_child(signal.SIGKILL)
+        supervisor_record_path(self.alias).unlink(missing_ok=True)
+        return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="manta-supervisor",
+        description="Own a manta_node child and its restart (ADR-0041 boundary B1).",
+    )
+    parser.add_argument("alias", help="node alias (the config name it starts)")
+    parser.add_argument("--config", help="config name (defaults to the alias)")
+    parser.add_argument(
+        "--python",
+        help=(
+            "interpreter that runs the node child (defaults to the supervisor's"
+            " own; set it when the child runs from a separate version tree, 2c)"
+        ),
+    )
+    args = parser.parse_args(argv)
+    return Supervisor(
+        args.alias, args.config or args.alias, child_python=args.python
+    ).run()
+
+
+if __name__ == "__main__":
+    sys.exit(main())

manta_node/supervisor/records.py

@@ -0,0 +1,167 @@
+"""The two on-disk records the supervisor and the node keep for one instance.
+
+Under the split (ADR-0041 boundary B1) there are two processes and two records:
+
+- the **node instance record**, ``<id>.json`` — node-owned content (alias,
+  config, ``log_file``, manager host). The running node writes it; the
+  supervisor never does.
+- the **supervisor record**, ``<alias>.supervisor.json`` — supervisor-owned, and
+  the **pid of record**. Under ``--subprocess`` the child writes no instance
+  record (``start.py`` skips it), so on a supervised node this is the only record
+  present and the CLI's ``status``/``stop`` must read it.
+
+This module has no dependency on the node's domain: the supervisor is
+infrastructure, and a guard test pins that (``tests/.../test_supervisor_is_infrastructure``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+
+INSTANCE_DIR = Path.home() / ".manta" / "nodes" / "instances"
+
+SUPERVISOR_SUFFIX = ".supervisor.json"
+
+
+def supervisor_record_path(alias: str) -> Path:
+    """The supervisor record for ``alias`` (the pid of record)."""
+    return INSTANCE_DIR / f"{alias}{SUPERVISOR_SUFFIX}"
+
+
+def write_json_atomic(path: Path, data: dict) -> None:
+    """Write ``data`` as JSON so no reader ever sees a half-written file.
+
+    A tmp file beside the target plus ``replace`` — an atomic rename on the same
+    filesystem. A reader either sees the previous record or the new one.
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2))
+    tmp.replace(path)
+
+
+def read_json(path: Path) -> dict | None:
+    """Read a JSON object, or None if it is absent or unreadable/invalid."""
+    try:
+        return json.loads(path.read_text())
+    except (FileNotFoundError, ValueError, OSError):
+        return None
+
+
+def supervisor_record(
+    alias: str, supervisor_pid: int, child_pid: int | None, state: str
+) -> dict:
+    """The supervisor record's shape."""
+    return {
+        "alias": alias,
+        "supervisor_pid": supervisor_pid,
+        "child_pid": child_pid,
+        "state": state,
+        "start_time": datetime.now(timezone.utc).isoformat(),
+    }
+
+
+def is_alive(pid: int | None) -> bool:
+    """True when ``pid`` names a live process."""
+    if not pid:
+        return False
+    try:
+        os.kill(pid, 0)
+    except OSError:
+        return False
+    return True
+
+
+def pid_of_record(alias: str) -> tuple[int | None, str]:
+    """(pid, source) for ``alias``: the supervisor record wins when it is live.
+
+    The pid of record is the one a stop signals. Under the split that is the
+    supervisor's; the instance record (the node's own pid) is the fallback for a
+    node running without a supervisor.
+    """
+    sup = read_json(supervisor_record_path(alias))
+    if sup and is_alive(sup.get("supervisor_pid")):
+        return sup["supervisor_pid"], "supervisor"
+
+    # Fall back to the node instance record: the supervisor may be absent (a node
+    # on the pre-split path) or dead. Match on the record's own alias, not the
+    # filename stem, which carries the per-start instance id.
+    for record in sorted(INSTANCE_DIR.glob("*.json")):
+        if record.name.endswith(SUPERVISOR_SUFFIX):
+            continue
+        data = read_json(record)
+        if data and data.get("alias") == alias and is_alive(data.get("pid")):
+            return data["pid"], "instance"
+    return None, "none"
+
+
+def list_instances() -> list[dict]:
+    """Live instances for the CLI, one per alias: the pid of record and its source.
+
+    A supervised node has only a supervisor record; a pre-split node has only an
+    instance record. A stale record (the pid is gone) is not returned, and its
+    file is removed — the same cleanup the CLI did before the split.
+    """
+    # Collect the two kinds separately, then resolve per alias with an EXPLICIT
+    # rule — never by filename/glob order. A supervisor record always wins over a
+    # node instance record for the same alias (as `pid_of_record` does); relying
+    # on sort order would let a legacy instance record silently override a live
+    # supervisor record whenever its config name sorts after the alias.
+    supervisors: dict[str, dict] = {}
+    instances: dict[str, dict] = {}
+
+    for record in sorted(INSTANCE_DIR.glob("*.json")):
+        data = read_json(record)
+        if data is None:
+            record.unlink(missing_ok=True)
+            continue
+
+        if record.name.endswith(SUPERVISOR_SUFFIX):
+            alias = data.get("alias")
+            pid = data.get("supervisor_pid")
+            entry = {
+                "alias": alias,
+                "instance_id": alias,
+                "config_name": alias,
+                "pid": pid,
+                # The child is the workload the operator cares about: `status`
+                # reports ITS cpu/memory, not the thin supervisor's. `pid` stays
+                # the pid of record (the supervisor) — what a stop signals.
+                "child_pid": data.get("child_pid"),
+                "workload_pid": data.get("child_pid"),
+                "source": "supervisor",
+                "start_time": data.get("start_time"),
+                "instance_file": record,
+            }
+            bucket = supervisors
+        else:
+            instance_id = data.get("instance_id", record.stem)
+            alias = data.get("alias", instance_id)
+            pid = data.get("pid")
+            entry = {
+                "alias": alias,
+                "instance_id": instance_id,
+                "config_name": data.get("config_name", "unknown"),
+                "pid": pid,
+                "child_pid": None,
+                "workload_pid": pid,
+                "source": "instance",
+                "start_time": data.get("start_time"),
+                "instance_file": record,
+            }
+            bucket = instances
+
+        if not alias or not is_alive(pid):
+            # A stale record is not a running instance: remove it so the next
+            # `status` does not keep reporting a dead pid.
+            record.unlink(missing_ok=True)
+            continue
+
+        bucket[alias] = entry
+
+    # Explicit precedence: the supervisor record wins for an alias that has both.
+    merged = {**instances, **supervisors}
+    return [merged[alias] for alias in sorted(merged)]

manta_node/supervisor/seam.py

@@ -0,0 +1,190 @@
+"""The supervisor's Unix-socket adapter for the local seam.
+
+The seam's **port** is ``manta_node.seam`` (the node/domain's interface); this
+module is the supervisor's **adapter** that serves it (mechanism §6.4). It is
+infrastructure: it carries a request in and an outcome out, and decides nothing.
+
+**Unused ⇒ no behaviour change.** The adapter is only started when the supervisor
+is asked to serve the seam; nothing connects to it until the node relays. That is
+the 2b acceptance: the code can ship, be idle, and change nothing.
+
+**Transport.** A Unix domain socket owned by the service user, at
+``~/.manta/supervisor.sock`` (the state dir, never the version tree — NF-6), with
+``0600`` on the socket and its parent directory. Local and same-user only
+(NF-9/NF-10).
+
+**What "execute" means here.** At 2b the supervisor has no version tree yet, so
+its executor is a stub: it records the request, idempotently, and answers
+``REQUESTED`` (or ``REFUSED`` for a repeat that is still in flight). The real
+fetch/verify/stage/switch/restart/revert lifecycle is 2c/2d; the seam's contract
+is what this lands.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import os
+from pathlib import Path
+
+from ..seam import (
+    SeamError,
+    SeamState,
+    SwitchOutcome,
+    UpdateRequest,
+    seam_socket_path,
+)
+
+_SOCKET_MODE = 0o600
+_DIR_MODE = 0o700
+
+
+class SeamServer:
+    """Serves the seam on a Unix socket; asks a handler for each outcome.
+
+    ``handler`` is ``async (UpdateRequest) -> SwitchOutcome`` — the executor. At
+    2b it is the stub below; at 2c/2d it becomes the real lifecycle.
+    """
+
+    def __init__(self, socket_path: Path | None = None) -> None:
+        self.socket_path = socket_path or seam_socket_path()
+        self._server: asyncio.AbstractServer | None = None
+        # Idempotency (NF-5): request_id -> the outcome already answered for it.
+        self._answered: dict[str, SwitchOutcome] = {}
+        self._in_flight: set[str] = set()
+
+    async def _read_request(self, reader: asyncio.StreamReader) -> UpdateRequest:
+        raw = await reader.readline()
+        if not raw:
+            raise SeamError("empty request")
+        try:
+            return UpdateRequest.from_bytes(raw.strip())
+        except (ValueError, KeyError) as exc:
+            raise SeamError(f"malformed request: {exc}") from exc
+
+    async def _handle_connection(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        handler,
+    ) -> None:
+        try:
+            request = await self._read_request(reader)
+            outcome = await self._answer(request, handler)
+            writer.write(outcome.to_bytes() + b"\n")
+            await writer.drain()
+        except SeamError as exc:
+            # A malformed request gets no outcome; the error is the answer.
+            writer.write(
+                SwitchOutcome(
+                    request_id="",
+                    state=SeamState.REFUSED,
+                    reason=str(exc),
+                ).to_bytes()
+                + b"\n"
+            )
+            with contextlib.suppress(ConnectionError):
+                await writer.drain()
+        finally:
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
+
+    async def _answer(self, request: UpdateRequest, handler) -> SwitchOutcome:
+        # Idempotency: a repeat of a completed request returns the same outcome;
+        # a repeat still in flight is refused, not run twice (NF-5).
+        if request.request_id in self._answered:
+            return self._answered[request.request_id]
+        if request.request_id in self._in_flight:
+            return SwitchOutcome(
+                request_id=request.request_id,
+                state=SeamState.REFUSED,
+                reason="a request with this request_id is already in flight",
+            )
+        self._in_flight.add(request.request_id)
+        try:
+            outcome = await handler(request)
+        finally:
+            self._in_flight.discard(request.request_id)
+        self._answered[request.request_id] = outcome
+        return outcome
+
+    async def start(self, handler) -> None:
+        """Bind the socket (0600, in a 0700 parent) and serve until stopped."""
+        parent = self.socket_path.parent
+        # `mkdir(mode=...)` only applies the mode when it CREATES the directory.
+        # `~/.manta` is usually created earlier by the config/log paths at the
+        # default umask, so chmod it explicitly: the socket's parent must be 0700
+        # even when it already existed (NF-9/NF-10).
+        parent.mkdir(parents=True, exist_ok=True)
+        os.chmod(parent, _DIR_MODE)
+        # A stale socket from a previous supervisor would make `bind` fail; it is
+        # ours to remove (same user, same path), and nothing else listens on it.
+        self.socket_path.unlink(missing_ok=True)
+        # The parent is 0700 before `bind`, so no non-owner can even reach the
+        # socket path; `chmod` after the bind then asserts the socket's own 0600
+        # (NF-9). No umask is set: it is process-wide, and `start_unix_server`
+        # yields before returning, so a tightened mask would leak across the
+        # await to any concurrent file creation.
+        self._server = await asyncio.start_unix_server(
+            lambda r, w: self._handle_connection(r, w, handler),
+            path=str(self.socket_path),
+        )
+        os.chmod(self.socket_path, _SOCKET_MODE)
+        async with self._server:
+            await self._server.serve_forever()
+
+    async def stop(self) -> None:
+        if self._server is not None:
+            self._server.close()
+            with contextlib.suppress(Exception):
+                await self._server.wait_closed()
+            self._server = None
+        self.socket_path.unlink(missing_ok=True)
+
+
+async def stub_handler(request: UpdateRequest) -> SwitchOutcome:
+    """The 2b executor: accept and record; the lifecycle is 2c/2d.
+
+    It makes no decision about versions — it answers ``REQUESTED`` so the seam's
+    contract is exercised end to end without a version tree.
+    """
+    return SwitchOutcome(
+        request_id=request.request_id,
+        state=SeamState.REQUESTED,
+        reason="accepted; the switch lifecycle lands in 2c/2d",
+        detail={"target": request.target, "force": request.force},
+    )
+
+
+class SocketSeamClient:
+    """The port's adapter over the supervisor's Unix socket (the node's side).
+
+    Implements ``manta_node.seam.SeamClient``. A connect failure raises
+    ``SeamError``: the node reports it and mutates nothing (NF-3).
+    """
+
+    def __init__(self, socket_path: Path | None = None) -> None:
+        self.socket_path = socket_path or seam_socket_path()
+
+    async def request_update(self, request: UpdateRequest) -> SwitchOutcome:
+        try:
+            reader, writer = await asyncio.open_unix_connection(str(self.socket_path))
+        except OSError as exc:
+            raise SeamError(f"seam unreachable at {self.socket_path}: {exc}") from exc
+        try:
+            writer.write(request.to_bytes() + b"\n")
+            await writer.drain()
+            raw = await reader.readline()
+        except OSError as exc:
+            raise SeamError(f"seam failed mid-request: {exc}") from exc
+        finally:
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
+        if not raw:
+            raise SeamError("seam closed without an outcome")
+        try:
+            return SwitchOutcome.from_bytes(raw.strip())
+        except (ValueError, KeyError) as exc:
+            raise SeamError(f"malformed outcome: {exc}") from exc

{manta_node-0.6b5.dev697.dist-info → manta_node-0.6b5.dev702.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: manta_node
-Version: 0.6b5.dev697
+Version: 0.6b5.dev702
 Summary: Node side software of the Manta platform. It is responsible for the communication with the Manta Core and the execution of the tasks.
 Author-email: Hugo Miralles <hugo.miralles@manta-tech.io>, Matthew Thompson <matthew.thompson@manta-tech.io>
 License-Expression: AGPL-3.0-or-later

{manta_node-0.6b5.dev697.dist-info → manta_node-0.6b5.dev702.dist-info}/RECORD

@@ -1,11 +1,12 @@
 manta_node/__init__.py,sha256=bgGWXH3yQVhNf0v1ZGUBAy5Y51fqb0Y-EaLnocbcino,153
 manta_node/__main__.py,sha256=SjrJyuMg_ZFKV6WOVe3MrtWM8Qmu065dkKZYl4n2YLw,1665
 manta_node/node_orchestrator.py,sha256=K2UZAk-FHs1ERrwf5hTcrQC2AASG2J2eVlr-l45aDt4,28066
+manta_node/seam.py,sha256=wAI3uL1iuV6pmDOaBW7WZi7_V7-NsHQDP6C_gFIjCiA,4747
 manta_node/task_manager.py,sha256=xRE-yKdUW0FFR8vtX1jDwl1AxTbqVD_JS7QVR62GA00,38002
 manta_node/tasks.py,sha256=o837Hi-KFVJg9LF5iOtE8oD6UuTOfrEPWR-JOdhRGeY,6983
 manta_node/utils.py,sha256=Hw4Iw2jYQYsfVLVJuBMt-_rMFBeml3nCDE2jiiXc8YM,1155
 manta_node/cli/__init__.py,sha256=arzO3mXDJ-E2yeeytbZfN7mCswwxdQ43_QjyeL2E5yE,134
-manta_node/cli/_version_generated.py,sha256=U8tnsuCO0NubWEyVUBj6fAkDGgNGnB4pplg1P5LTHJA,275
+manta_node/cli/_version_generated.py,sha256=lUZps58EgIuYIAwnIQz2-ijOxuSzZ_io_eQmog7Eujc,275
 manta_node/cli/config_manager.py,sha256=BCju9zqzraviL3KrzRnB-vZQUY__Q5kuEqb7EdB8YdI,4409
 manta_node/cli/main.py,sha256=dZa6zrypWBvpN8hd4qpxevvlyNFhxKINCg1537NJ36w,4318
 manta_node/cli/version.py,sha256=3lrnIWpOosszBN-VsCBVLxDgpvCC7IB0aDIKx_3e7hI,3115
@@ -15,8 +16,8 @@ manta_node/cli/commands/config.py,sha256=BiarCD0S8rcNYbio4RLzDvUS7A50s5dd5F4TiZq
 manta_node/cli/commands/logs.py,sha256=cXOSdwhDIJAiKMmJYdzrnpapIxudxVdMzYT-KAWDKVk,5259
 manta_node/cli/commands/network.py,sha256=QqncD6vbNlg65ptQdFYexEUMALQm8UwcftbW3sfQrjw,42070
 manta_node/cli/commands/start.py,sha256=HuIovoL3a1yQuEIIZMmvRUu3mq1cKJlFZgBf-U2zS7A,25637
-manta_node/cli/commands/status.py,sha256=FhlJuFxIRzxv9y8jUJRuWaCLfDBsGBqv6DCHUFQta3A,6401
-manta_node/cli/commands/stop.py,sha256=8on7NqqaBeHRcbrZ5pGJ3Ms_6E_HNcF22mZ908JVu4A,7695
+manta_node/cli/commands/status.py,sha256=I3z4bee0uqobEhA4akJ3OErRJ7_UcieW6tvLP3pyZ-A,5608
+manta_node/cli/commands/stop.py,sha256=bGsvDrTiIvDN20HMsXKQYg83iWRaAnhbJ8xcalJwre0,9117
 manta_node/domain/__init__.py,sha256=uyJXDf0QgfGCsXLMggqKCB5QV9oneYJ4iM-REaJGXDM,217
 manta_node/domain/task_lifecycle.py,sha256=CmaK6OL4KNSy81YYosINduVQQW3LjycAwmfpRmXrldk,3323
 manta_node/domain/value_objects/__init__.py,sha256=Sut2I8iSNNYBtI42-tfKXJ8aod2HV_k_N_uM_KWwjqs,135
@@ -40,7 +41,7 @@ manta_node/infrastructure/metrics/__init__.py,sha256=ODGAj9s63F5jba2c3dQRMfNK6I4
 manta_node/infrastructure/metrics/collector.py,sha256=9ESw__Pc2tV6ldG5yhos2IS7T5Td59KxTIwDRZc_G4w,3067
 manta_node/infrastructure/metrics/metrics_collector.py,sha256=TI_9tRoIUunGx_BstVavK6VElig7Wc5mJ0kB4bFumVs,11048
 manta_node/infrastructure/mqtt/__init__.py,sha256=riXo1sXgO4YV6DHCmWRqK61BAmuGLdHiVdQFunAJadA,140
-manta_node/infrastructure/mqtt/command_handler.py,sha256=YaRPhOvgo4MSQksnhOCAT-Op9Zyl-yNCuoeXchcHeSk,26791
+manta_node/infrastructure/mqtt/command_handler.py,sha256=Ym8t0fA-qWjg8n0VDyYJYxCqulVH3lOJB1MjQHu5iZE,28110
 manta_node/infrastructure/network/__init__.py,sha256=On3XLgycFQoc-fBCa5hFuFDfEJjmFy7Wl2CK3D2LkdI,478
 manta_node/infrastructure/network/event_registry.py,sha256=iWEfUJRzDnWjOrDinpYqVyIUpGKJjp7RZkjMDPfpplM,1661
 manta_node/infrastructure/network/factory.py,sha256=-LvHbBp5nBpQ7fyQT1T0pvK3aczZqWc9QNDW37brBeU,3897
@@ -51,9 +52,13 @@ manta_node/infrastructure/process/executor.py,sha256=Ab1XvNuelEGCD5KdZLgYYnpjYZ5
 manta_node/infrastructure/security/__init__.py,sha256=lI6vkbUmfmt0m363iO4HzuzVNoQAc7Clp2R5vAhZbgE,64
 manta_node/infrastructure/security/auth_agent.py,sha256=WkPTg_g0gix7xomb_on_Ft3TNX0FpeqS7gwgJW9mTvk,11037
 manta_node/infrastructure/security/token_provider.py,sha256=u3bcbQYNBskFzunO-wOSZpGkDN_CU1BCB5HUbZTC4Vg,1832
-manta_node-0.6b5.dev697.dist-info/licenses/LICENSE,sha256=9mBgLhiB9goQPQjg9XQJ6FjgVxYw9Q8lyOZYkPGwF_c,34484
-manta_node-0.6b5.dev697.dist-info/METADATA,sha256=ffSLua9Ci0UH0_YNS2WKaeQcj6K0A7MpGQAvC3sZedE,4231
-manta_node-0.6b5.dev697.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
-manta_node-0.6b5.dev697.dist-info/entry_points.txt,sha256=C_zcw6mdmztNxVUZGLZ83UH5TwcSuqb2C-rB4e2CQoc,56
-manta_node-0.6b5.dev697.dist-info/top_level.txt,sha256=nbT5J5WETuXM9UPoQckl29uUOq8wMYdRb9QDx5kAFeo,11
-manta_node-0.6b5.dev697.dist-info/RECORD,,
+manta_node/supervisor/__init__.py,sha256=kgdoNce1tM4e7jvdxkdmnNJV1L92-NI2cRfYSdm9vsw,542
+manta_node/supervisor/process.py,sha256=is3phcIKF9AdRORqXK7_rwiiqCF_4t4txXu-vGtUOE8,8655
+manta_node/supervisor/records.py,sha256=fUlL1SfmWpGnCbJ9956cuy0H3a7-aEF-B-naqbJiYoU,6405
+manta_node/supervisor/seam.py,sha256=zafKSWFeZClprftM0tYaTW3Ng7lxeFcndRIHplpSnf4,7708
+manta_node-0.6b5.dev702.dist-info/licenses/LICENSE,sha256=9mBgLhiB9goQPQjg9XQJ6FjgVxYw9Q8lyOZYkPGwF_c,34484
+manta_node-0.6b5.dev702.dist-info/METADATA,sha256=5JY-PMYelVoodkp4dK-vs1D-lNTNWd-lHT0NzZ_6tXE,4231
+manta_node-0.6b5.dev702.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+manta_node-0.6b5.dev702.dist-info/entry_points.txt,sha256=uCwggRApalLEsYs1YxwTBN0-e9oMJAkMoBp01HaSdoY,110
+manta_node-0.6b5.dev702.dist-info/top_level.txt,sha256=nbT5J5WETuXM9UPoQckl29uUOq8wMYdRb9QDx5kAFeo,11
+manta_node-0.6b5.dev702.dist-info/RECORD,,

{manta_node-0.6b5.dev697.dist-info → manta_node-0.6b5.dev702.dist-info}/entry_points.txt

@@ -1,2 +1,3 @@
 [console_scripts]
+manta-supervisor = manta_node.supervisor.process:main
 manta_node = manta_node.__main__:main