@topy-ai/maggie 0.7.53 → 0.7.55

package/bundled-tools/clis/maggie_feedback.py

@@ -20,6 +20,10 @@ from urllib.request import Request, urlopen
 
 
 DEFAULT_ENDPOINT = "https://feedback.noblox.app/api/feedback"
+# Both hosts accept the same anonymous contract and de-duplicate on feedbackId,
+# so a draft is offered to the next one only when the previous host failed
+# before storing it (network error or a 5xx such as Cloudflare's 52x).
+DEFAULT_ENDPOINTS = (DEFAULT_ENDPOINT, "https://feedback.cmo.so/api/feedback")
 SECRET_RE = re.compile(r"(?i)(bearer\s+|(?:api[_-]?key|token|secret|password|npm_config[^=]*|authorization)\s*[=:]\s*)[^\s,;]+")
 LOCAL_PATH_RE = re.compile(
     r"(?<![A-Za-z0-9])(?:~/(?:[^\s,;:)\]}]+/)*[^\s,;:)\]}]+|"
@@ -348,28 +352,52 @@ def hosted_payload(data: dict) -> dict:
     return payload
 
 
+def submit_endpoints(value: object) -> list[str]:
+    endpoints = [value] if isinstance(value, str) else list(value or DEFAULT_ENDPOINTS)
+    result = []
+    for endpoint in endpoints:
+        endpoint = str(endpoint).rstrip("/")
+        parsed = urlparse(endpoint)
+        if parsed.scheme != "https" or not parsed.netloc:
+            raise ValueError("endpoint must be an absolute HTTPS URL")
+        if endpoint not in result:
+            result.append(endpoint)
+    return result
+
+
 def submit(args: argparse.Namespace) -> int:
     if not args.confirm:
         raise ValueError("submit requires --confirm; feedback is never sent implicitly")
     path = Path(args.feedback)
     data = read_feedback(path)
-    endpoint = args.endpoint.rstrip("/")
-    parsed = urlparse(endpoint)
-    if parsed.scheme != "https" or not parsed.netloc:
-        raise ValueError("endpoint must be an absolute HTTPS URL")
+    endpoints = submit_endpoints(args.endpoint)
     payload = hosted_payload(data)
     payload["projectContext"] = data.get("projectContext") if data.get("privacy", {}).get("projectContextAllowed") else None
-    request = Request(endpoint, data=json.dumps(payload, ensure_ascii=False).encode(), headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "MaggieFeedback/0.1"}, method="POST")
-    try:
-        with urlopen(request, timeout=20) as response:
-            raw = response.read(1_000_000).decode("utf-8", "replace")
-            result = json.loads(raw) if raw else {}
-    except (HTTPError, URLError, TimeoutError) as error:
-        raise RuntimeError(f"feedback submission failed: {error}") from error
+    body = json.dumps(payload, ensure_ascii=False).encode()
+    failures = []
+    for endpoint in endpoints:
+        request = Request(endpoint, data=body, headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "MaggieFeedback/0.1"}, method="POST")
+        try:
+            with urlopen(request, timeout=20) as response:
+                raw = response.read(1_000_000).decode("utf-8", "replace")
+                result = json.loads(raw) if raw else {}
+            break
+        except HTTPError as error:
+            failures.append({"endpoint": endpoint, "error": f"HTTP {error.code}"})
+            # A 4xx is the host rejecting this draft; another host would too.
+            if error.code < 500:
+                raise RuntimeError(f"feedback submission failed: {endpoint} answered HTTP {error.code}") from error
+        except (URLError, TimeoutError, OSError) as error:
+            failures.append({"endpoint": endpoint, "error": safe_text(getattr(error, "reason", error))})
+    else:
+        tried = "; ".join(f"{item['endpoint']} ({item['error']})" for item in failures)
+        raise RuntimeError(f"feedback submission failed on every endpoint: {tried}")
     ack = acknowledgement(result)
     data["submission"] = {"status": "submitted", "endpoint": endpoint, "submittedAt": now(), "acknowledgement": ack}
+    if failures:
+        data["submission"]["failedEndpoints"] = failures
     path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "acknowledgement": ack}, indent=2, ensure_ascii=False))
+    print(json.dumps({"feedbackId": data["feedbackId"], "status": "submitted", "endpoint": endpoint, "failedEndpoints": failures, "acknowledgement": ack}, indent=2, ensure_ascii=False))
     return 0
 
 
@@ -815,7 +843,7 @@ def main() -> int:
     preview_parser.add_argument("--format", choices=("json", "markdown"), default="json")
     submit_parser = sub.add_parser("submit")
     submit_parser.add_argument("feedback")
-    submit_parser.add_argument("--endpoint", default=DEFAULT_ENDPOINT)
+    submit_parser.add_argument("--endpoint", action="append", help="HTTPS endpoint; repeat for an ordered fallback list (default: the NoBlox host, then feedback.cmo.so)")
     submit_parser.add_argument("--confirm", action="store_true")
     list_parser = sub.add_parser("list")
     list_parser.add_argument("--project", default=argparse.SUPPRESS)

package/bundled-tools/clis/maggie_host_runtime.py

@@ -0,0 +1,458 @@
+#!/usr/bin/env python3
+"""Host runtime checks for VPS hosts that serve PHP or containers (``maggie deployment ...``).
+
+- ``runtime-inventory``: read-only inventory of one host — OS release, every
+  active nginx server block (from ``nginx -T``, which includes files that are
+  symlinked into ``sites-enabled``; ``grep -r`` does not follow those links and
+  made a host look as if it had no PHP sites), its ``fastcgi_pass`` target,
+  host PHP versions and php-fpm units, containers and container units. With
+  ``--advisory`` it marks each runtime against the fixed versions and writes a
+  reviewable migration plan per affected site. It also flags an operating
+  system past its end of standard security support and a pinned container
+  tag older than the newest patch of its line (``--latest-tags``). Input is a
+  collected evidence file (``--evidence``) or ``--ssh user@host``, which runs
+  only the read-only collector printed by ``--print-collector``.
+- ``host-lock``: one agent session at a time on a production host. Acquire it
+  before editing systemd units, containers or nginx; ``status`` also lists
+  files changed recently under those directories (someone may be working
+  there without the lock). Two sessions once recreated the same container in
+  turn, each undoing the other's fix.
+
+PHP images (``php:*-fpm``, ``wordpress:*-fpm``) are always planned with
+``--entrypoint docker-php-entrypoint`` and an explicit ``php-fpm`` command:
+the WordPress image's own entrypoint copies a fresh WordPress into a mounted
+site folder that has no ``wp-config.php``, which once exposed a public
+``wp-admin/setup-config.php`` on a site that was not WordPress.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import shlex
+import subprocess
+import sys
+from datetime import date, datetime, timedelta, timezone
+from pathlib import Path
+
+# End of standard security support (not paid extended support). Override or
+# extend with --eol-table FILE ({"ubuntu": {"24.10": "2025-07-10"}}).
+EOL = {
+    "ubuntu": {
+        "16.04": "2021-04-30", "18.04": "2023-05-31", "20.04": "2025-05-31", "22.04": "2027-06-01",
+        "24.04": "2029-05-31", "26.04": "2031-05-31",
+        "20.10": "2021-07-22", "21.04": "2022-01-20", "21.10": "2022-07-14", "22.10": "2023-07-20",
+        "23.04": "2024-01-25", "23.10": "2024-07-11", "24.10": "2025-07-10", "25.04": "2026-01-15",
+        "25.10": "2026-07-09",
+    },
+    "debian": {"9": "2022-06-30", "10": "2024-06-30", "11": "2026-08-31", "12": "2028-06-30", "13": "2030-06-30"},
+}
+SECTION = re.compile(r"^### (\S+)\s*$")
+SAFE_NAME = re.compile(r"^[A-Za-z0-9._-]{1,64}$")
+PHP_IMAGE = re.compile(r"(^|/)(php|wordpress)(:|$)")
+
+# Read-only collector. Each section starts with "### name"; the parser ignores
+# anything it does not know. "nginx -T" prints every included file, so
+# symlinked sites-enabled entries are covered; the grep fallback uses -R.
+COLLECTOR = r"""set +e
+s() { printf '\n### %s\n' "$1"; }
+SUDO=""; [ "$(id -u)" != 0 ] && sudo -n true 2>/dev/null && SUDO="sudo -n"
+s os-release; cat /etc/os-release 2>/dev/null
+s nginx-T; $SUDO nginx -T 2>/dev/null
+s nginx-fastcgi-files; $SUDO grep -RIl fastcgi_pass /etc/nginx 2>/dev/null
+s php-v; php -v 2>/dev/null | head -1
+s php-fpm-units; systemctl list-units --all --no-legend --plain 'php*-fpm*' 2>/dev/null
+s docker-ps; $SUDO docker ps --format '{{.Names}}\t{{.Image}}\t{{.Ports}}\t{{.Mounts}}' 2>/dev/null
+s docker-entrypoints; $SUDO docker ps -q 2>/dev/null | xargs -r $SUDO docker inspect --format '{{.Name}}\t{{.Config.Image}}\t{{json .Config.Entrypoint}}' 2>/dev/null
+for f in $($SUDO grep -RlE '(docker|podman) run' /etc/systemd/system 2>/dev/null | sort -u); do s "unit:$f"; $SUDO cat "$f"; done
+"""
+
+
+def parse_sections(text: str) -> dict[str, str]:
+    sections: dict[str, list[str]] = {}
+    current = None
+    for line in text.splitlines():
+        match = SECTION.match(line)
+        if match:
+            current = match.group(1)
+            sections.setdefault(current, [])
+        elif current:
+            sections[current].append(line)
+    return {name: "\n".join(lines).strip("\n") for name, lines in sections.items()}
+
+
+def parse_os(text: str) -> dict:
+    values = {}
+    for line in text.splitlines():
+        if "=" in line:
+            key, _, value = line.partition("=")
+            values[key.strip()] = value.strip().strip('"')
+    return {"id": values.get("ID", ""), "version": values.get("VERSION_ID", ""), "name": values.get("PRETTY_NAME", "")}
+
+
+def os_finding(os_info: dict, today: date, table: dict) -> dict | None:
+    ends = table.get(os_info.get("id", ""), {}).get(os_info.get("version", ""))
+    if not ends:
+        return {"kind": "os-unknown", "severity": "warning", "message": f"no end-of-support date known for {os_info.get('name') or 'this OS'}; check it by hand or pass --eol-table"} if os_info.get("id") else None
+    end = date.fromisoformat(ends)
+    if end < today:
+        return {"kind": "os-eol", "severity": "error", "ends": ends, "message": f"{os_info['name']} stopped getting standard security fixes on {ends}; plan an upgrade to a supported release"}
+    if end - today < timedelta(days=120):
+        return {"kind": "os-eol-soon", "severity": "warning", "ends": ends, "message": f"{os_info['name']} stops getting standard security fixes on {ends}"}
+    return None
+
+
+def strip_comment(line: str) -> str:
+    return line.split("#", 1)[0]
+
+
+def parse_nginx(text: str) -> list[dict]:
+    """Server blocks from `nginx -T` output: file, server_name, root, listen, fastcgi_pass."""
+    servers: list[dict] = []
+    current_file = ""
+    depth = 0
+    server: dict | None = None
+    server_depth = 0
+    statements: list[str] = []
+    for raw in text.splitlines():
+        if re.match(r"^# configuration file (.+):\s*$", raw):
+            statements.append(raw)
+            continue
+        body = strip_comment(raw).replace("{", "{\n").replace("}", "\n}\n").replace(";", ";\n")
+        statements += [part.strip() for part in body.splitlines() if part.strip()]
+    for line in statements:
+        marker = re.match(r"^# configuration file (.+):\s*$", line)
+        if marker:
+            current_file = marker.group(1)
+            depth, server = 0, None
+            continue
+        if server is None and re.match(r"^server\s*\{", line):
+            server = {"file": current_file, "serverNames": [], "root": "", "listen": [], "fastcgiPass": []}
+            server_depth = depth + 1
+        if server is not None:
+            for directive, key in (("server_name", "serverNames"), ("listen", "listen"), ("fastcgi_pass", "fastcgiPass")):
+                match = re.match(rf"^{directive}\s+([^;]+);", line)
+                if match:
+                    values = match.group(1).split() if directive == "server_name" else [match.group(1).strip()]
+                    for value in values:
+                        if value not in server[key]:
+                            server[key].append(value)
+            match = re.match(r"^root\s+([^;]+);", line)
+            if match and not server["root"]:
+                server["root"] = match.group(1).strip()
+        depth += line.count("{") - line.count("}")
+        if server is not None and depth < server_depth:
+            servers.append(server)
+            server = None
+    return servers
+
+
+def version_tuple(value: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in re.findall(r"\d+", value)[:3])
+
+
+def php_line(value: str) -> str:
+    match = re.search(r"(\d+)\.(\d+)", value)
+    return f"{match.group(1)}.{match.group(2)}" if match else ""
+
+
+def parse_containers(text: str) -> list[dict]:
+    containers = []
+    for line in text.splitlines():
+        parts = line.split("\t")
+        if len(parts) < 2 or not parts[0].strip():
+            continue
+        name, image = parts[0].strip(), parts[1].strip()
+        ports = parts[2] if len(parts) > 2 else ""
+        bound = re.findall(r"(?:([\d.]+|\[::\]):)?(\d+)->(\d+)/tcp", ports)
+        containers.append({"name": name, "image": image, "ports": [{"host": host or "0.0.0.0", "hostPort": int(hp), "containerPort": int(cp)} for host, hp, cp in bound], "mounts": parts[3].strip() if len(parts) > 3 else ""})
+    return containers
+
+
+def image_info(image: str) -> dict:
+    repo, _, tag = image.rpartition(":") if ":" in image.split("/")[-1] else (image, "", "latest")
+    name = repo.split("/")[-1]
+    php = re.search(r"(?:^|php)(\d+\.\d+(?:\.\d+)?)", tag)
+    version = php.group(1) if php and (name == "php" or "php" in tag) else ""
+    return {"repository": name, "tag": tag, "php": version, "line": php_line(version), "patchPinned": version.count(".") == 2, "isPhp": bool(PHP_IMAGE.search(image))}
+
+
+def unit_findings(units: dict[str, str]) -> list[dict]:
+    findings = []
+    for path, body in units.items():
+        for match in re.finditer(r"(?:docker|podman) run[^\n]*", re.sub(r"\\\s*\n", " ", body)):
+            command = match.group(0)
+            image = next((token for token in command.split() if PHP_IMAGE.search(token) and ":" in token), "")
+            if image and "--entrypoint docker-php-entrypoint" not in command and "--entrypoint=docker-php-entrypoint" not in command:
+                findings.append({"kind": "php-image-entrypoint", "severity": "error", "unit": path, "image": image,
+                                 "message": f"{path} runs {image} with the image's own entrypoint; add --entrypoint docker-php-entrypoint and an explicit php-fpm command (the WordPress entrypoint copies WordPress into a mounted folder without wp-config.php)"})
+    return findings
+
+
+def runtime_status(version: str, advisory: dict | None) -> str:
+    if not advisory:
+        return "not-checked"
+    line = php_line(version)
+    fixed = (advisory.get("fixed") or {}).get(line)
+    if not line:
+        return "unknown"
+    if not fixed:
+        lines = sorted((advisory.get("fixed") or {}), key=version_tuple)
+        if line in (advisory.get("unsupportedLines") or []) or (lines and version_tuple(line) < version_tuple(lines[0])):
+            return "affected-no-fix"
+        return "not-listed"
+    if version.count(".") < 2:
+        return "unknown-patch"
+    return "affected" if version_tuple(version) < version_tuple(fixed) else "fixed"
+
+
+def resolve_runtime(target: str, host_php: str, fpm_units: list[str], containers: list[dict]) -> dict:
+    socket = re.search(r"php(\d+\.\d+)-fpm", target)
+    if target.startswith("unix:") and socket:
+        line = socket.group(1)
+        version = host_php if php_line(host_php) == line else line
+        return {"kind": "host-php-fpm", "unit": f"php{line}-fpm", "version": version}
+    port = re.search(r"(?:^|:)(\d+)$", target)
+    if port:
+        for container in containers:
+            if any(p["hostPort"] == int(port.group(1)) for p in container["ports"]):
+                info = image_info(container["image"])
+                return {"kind": "container", "container": container["name"], "image": container["image"], "version": info["php"]}
+    if target.startswith("unix:") and fpm_units:
+        return {"kind": "host-php-fpm", "unit": fpm_units[0], "version": host_php}
+    return {"kind": "unknown", "version": ""}
+
+
+def site_slug(server: dict) -> str:
+    name = next((n for n in server["serverNames"] if n not in ("_", "localhost")), "") or Path(server["file"]).name
+    return re.sub(r"[^a-z0-9]+", "-", name.lower()).strip("-")[:40] or "site"
+
+
+def migration_plan(server: dict, runtime: dict, image: str, port: int, writable: list[str]) -> dict:
+    slug = site_slug(server)
+    root = server["root"] or "/var/www/SITE"
+    container = f"php-{slug}"
+    mounts = [f"{root}:{root}:ro"] + [f"{path}:{path}" for path in writable if path.startswith(root)]
+    run = ["docker", "run", "-d", "--name", container, "--restart", "unless-stopped",
+           "--entrypoint", "docker-php-entrypoint", "--user", "SITE_UID:SITE_GID", "-p", f"127.0.0.1:{port}:9000"]
+    for mount in mounts:
+        run += ["-v", mount]
+    run += [image, "php-fpm"]
+    old = runtime.get("target", "")
+    host = next((n for n in server["serverNames"] if n not in ("_", "localhost")), "SITE_HOST")
+    listing = f"/root/maggie-{slug}-files-before.txt"
+    return {
+        "site": host, "nginxFile": server["file"], "root": root, "currentRuntime": runtime, "image": image,
+        "steps": [
+            f"maggie deployment host-lock acquire --host HOST --session SESSION  # before any change",
+            f"stat -c '%u:%g' {shlex.quote(root)}  # SITE_UID:SITE_GID for --user",
+            f"find {shlex.quote(root)} -xdev -type f | sort > {listing}",
+            f"docker pull {image}",
+            " ".join(shlex.quote(part) for part in run),
+            f"cp -a {shlex.quote(server['file'])} {shlex.quote(server['file'])}.maggie-bak",
+            f"sed -i 's#fastcgi_pass {old};#fastcgi_pass 127.0.0.1:{port};#' {shlex.quote(server['file'])}",
+            "nginx -t && systemctl reload nginx",
+        ],
+        "systemdUnit": "If the container is managed by a systemd unit, its ExecStart must carry the same --entrypoint docker-php-entrypoint and php-fpm command; recreate through the unit, not by hand, or the next restart brings the old command back.",
+        "verify": [
+            f"find {shlex.quote(root)} -xdev -type f | sort | diff {listing} -  # must print nothing: no files appeared",
+            f"curl -s -o /dev/null -w '%{{http_code}}' https://{host}/wp-admin/setup-config.php  # must not be 200 (404 on a site that is not WordPress)",
+            f"curl -sI https://{host}/ | head -1  # the site still answers as before",
+            f"docker exec {container} php -v | head -1  # the patched version",
+        ],
+        "rollback": [
+            f"cp -a {shlex.quote(server['file'])}.maggie-bak {shlex.quote(server['file'])} && nginx -t && systemctl reload nginx",
+            f"docker rm -f {container}",
+        ],
+        "mutation": "not executed",
+    }
+
+
+def inventory(evidence_text: str, advisory: dict | None, latest_tags: dict, today: date, eol_table: dict, image_template: str, base_port: int, writable: list[str]) -> dict:
+    sections = parse_sections(evidence_text)
+    findings: list[dict] = []
+    os_info = parse_os(sections.get("os-release", ""))
+    if (finding := os_finding(os_info, today, eol_table)):
+        findings.append(finding)
+    nginx_text = sections.get("nginx-T", "")
+    if not nginx_text.strip():
+        findings.append({"kind": "nginx-unread", "severity": "warning", "message": "no `nginx -T` output: config discovery must follow sites-enabled symlinks (nginx -T or grep -R, never grep -r)"})
+    servers = parse_nginx(nginx_text)
+    host_php = (re.search(r"PHP (\d+\.\d+\.\d+)", sections.get("php-v", "")) or [None, ""])[1]
+    fpm_units = [line.split()[0] for line in sections.get("php-fpm-units", "").splitlines() if line.strip()]
+    containers = parse_containers(sections.get("docker-ps", ""))
+    units = {name[5:]: body for name, body in sections.items() if name.startswith("unit:")}
+    findings += unit_findings(units)
+    for line in sections.get("docker-entrypoints", "").splitlines():
+        parts = line.split("\t")
+        if len(parts) == 3 and PHP_IMAGE.search(parts[1]) and "docker-php-entrypoint" not in parts[2]:
+            findings.append({"kind": "php-image-entrypoint", "severity": "error", "container": parts[0].lstrip("/"), "image": parts[1],
+                             "message": f"container {parts[0].lstrip('/')} runs {parts[1]} with entrypoint {parts[2]}; recreate it with --entrypoint docker-php-entrypoint and an explicit php-fpm command"})
+    for container in containers:
+        info = image_info(container["image"])
+        newest = ((latest_tags.get(info["repository"]) or {}).get(info["line"]) if info["line"] else None)
+        if info["patchPinned"] and newest and version_tuple(info["php"]) < version_tuple(newest):
+            findings.append({"kind": "image-stale", "severity": "warning", "container": container["name"], "image": container["image"], "newest": newest,
+                             "message": f"{container['image']} is pinned to {info['php']}; the newest patch of {info['line']} is {newest}"})
+        exposed = [p for p in container["ports"] if p["host"] not in ("127.0.0.1", "::1")]
+        if info["isPhp"] and exposed:
+            findings.append({"kind": "fpm-port-public", "severity": "error", "container": container["name"], "message": f"{container['name']} publishes php-fpm on {exposed[0]['host']}:{exposed[0]['hostPort']}; bind it to 127.0.0.1"})
+    used_ports = {p["hostPort"] for c in containers for p in c["ports"]}
+    port = base_port
+    sites, plans = [], []
+    for server in servers:
+        if not server["fastcgiPass"]:
+            continue
+        for target in server["fastcgiPass"]:
+            runtime = resolve_runtime(target, host_php, fpm_units, containers)
+            runtime["target"] = target
+            status = runtime_status(runtime.get("version", ""), advisory)
+            sites.append({"site": next(iter(server["serverNames"]), ""), "nginxFile": server["file"], "root": server["root"], "runtime": runtime, "status": status})
+            if status in ("affected", "affected-no-fix", "unknown-patch") and advisory:
+                line = php_line(runtime.get("version", ""))
+                fixes = advisory.get("fixed") or {}
+                fixed = fixes.get(line) or (max(fixes.values(), key=version_tuple) if fixes else line)
+                while port in used_ports:
+                    port += 1
+                used_ports.add(port)
+                plans.append(migration_plan(server, runtime, image_template.format(version=fixed, line=php_line(fixed)), port, writable))
+    affected = [s for s in sites if s["status"] in ("affected", "affected-no-fix")]
+    return {
+        "schemaVersion": "maggie-host-runtime-inventory.v1",
+        "os": os_info, "hostPhp": host_php, "phpFpmUnits": fpm_units, "containers": containers,
+        "sites": sites, "advisory": (advisory or {}).get("id"), "affectedSites": len(affected),
+        "findings": findings, "migrationPlans": plans,
+        "passed": not affected and not any(f["severity"] == "error" for f in findings),
+        "mutation": "not executed",
+    }
+
+
+def collect_ssh(target: str, ssh_args: list[str]) -> str:
+    command = ["ssh", "-o", "BatchMode=yes", *ssh_args, target, "bash -s"]
+    completed = subprocess.run(command, input=COLLECTOR.encode(), capture_output=True, timeout=300, check=False)
+    if completed.returncode not in (0, 1) and not completed.stdout:
+        raise OSError(f"collector failed on {target} (exit {completed.returncode})")
+    return completed.stdout.decode("utf-8", "replace")
+
+
+# --- host lock -----------------------------------------------------------------
+
+LOCK_SCRIPT = r"""set -u
+LOCK=$1; ACTION=$2; SESSION=$3; TTL=$4; PURPOSE=$5; FORCE=$6; MINUTES=$7; shift 7
+NOW=$(date +%s)
+exec 9>"$LOCK.guard" || exit 3
+flock -w 10 9 || exit 3
+HOLDER=""; EXPIRES=0
+if [ -f "$LOCK" ]; then HOLDER=$(sed -n 's/^session=//p' "$LOCK"); EXPIRES=$(sed -n 's/^expires=//p' "$LOCK"); fi
+held() { [ -n "$HOLDER" ] && [ "$HOLDER" != "$SESSION" ] && [ "${EXPIRES:-0}" -gt "$NOW" ]; }
+echo "### lock"; [ -f "$LOCK" ] && cat "$LOCK"
+echo "### recent"; find -L "$@" -xdev -type f -mmin "-$MINUTES" 2>/dev/null | head -50
+case "$ACTION" in
+  acquire)
+    if held; then echo "### result"; echo held; exit 10; fi
+    printf 'session=%s\nacquired=%s\nexpires=%s\npurpose=%s\nuser=%s\n' "$SESSION" "$NOW" "$((NOW + TTL))" "$PURPOSE" "$(id -un)" > "$LOCK.tmp" && mv "$LOCK.tmp" "$LOCK"
+    echo "### result"; echo acquired;;
+  release)
+    if held && [ "$FORCE" != 1 ]; then echo "### result"; echo held; exit 10; fi
+    rm -f "$LOCK"; echo "### result"; echo released;;
+  *) echo "### result"; if held; then echo held; elif [ -n "$HOLDER" ] && [ "${EXPIRES:-0}" -gt "$NOW" ]; then echo mine; else echo free; fi;;
+esac
+"""
+WATCH = ["/etc/systemd/system", "/etc/nginx", "/etc/containers/systemd", "/etc/docker"]
+
+
+def host_lock(action: str, host: str, session: str, ttl: int, purpose: str, force: bool, minutes: int, lock_path: str, watch: list[str], ssh_args: list[str]) -> dict:
+    if not SAFE_NAME.match(session):
+        raise ValueError("--session must be 1-64 letters, digits, dot, dash or underscore")
+    argv = [lock_path, action, session, str(ttl), re.sub(r"[\n\r]", " ", purpose)[:120], "1" if force else "0", str(minutes), *watch]
+    if host == "local":
+        command = ["bash", "-c", LOCK_SCRIPT, "lock", *argv]
+    else:
+        command = ["ssh", "-o", "BatchMode=yes", *ssh_args, host, "bash -c " + shlex.quote(LOCK_SCRIPT) + " lock " + " ".join(shlex.quote(a) for a in argv)]
+    completed = subprocess.run(command, capture_output=True, text=True, timeout=60, check=False)
+    if completed.returncode == 3:
+        raise OSError("could not take the lock guard (another command is holding it, or the lock folder is not writable)")
+    sections = parse_sections(completed.stdout)
+    lock = dict(line.split("=", 1) for line in sections.get("lock", "").splitlines() if "=" in line)
+    result = sections.get("result", "").strip() or "error"
+    if "expires" in lock:
+        lock["expiresAt"] = datetime.fromtimestamp(int(lock["expires"]), timezone.utc).isoformat()
+    recent = [line for line in sections.get("recent", "").splitlines() if line.strip() and not line.startswith(lock_path)]
+    report = {"schemaVersion": "maggie-host-lock.v1", "host": host, "action": action, "session": session, "result": result,
+              "lock": lock, "recentChanges": recent, "recentMinutes": minutes,
+              "passed": result in ("acquired", "released", "mine", "free")}
+    if result == "held":
+        report["message"] = f"another session ({lock.get('session')}, {lock.get('purpose') or 'no purpose given'}) holds this host until {lock.get('expiresAt')}; wait, or ask whoever runs it to stop. Do not edit units, containers or nginx meanwhile."
+    elif recent:
+        report["message"] = f"{len(recent)} file(s) under the watched folders changed in the last {minutes} minutes; make sure each is yours before editing."
+    return report
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie deployment", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    ssh_parent = argparse.ArgumentParser(add_help=False)
+    ssh_parent.add_argument("--ssh-key")
+    ssh_parent.add_argument("--ssh-port", default="22")
+    ri = sub.add_parser("runtime-inventory", parents=[ssh_parent], help="read-only PHP/runtime inventory of a host, with an advisory check and migration plans")
+    source = ri.add_mutually_exclusive_group()
+    source.add_argument("--evidence", type=Path, help="collector output saved from the host")
+    source.add_argument("--ssh", help="user@host: run the read-only collector over ssh")
+    source.add_argument("--print-collector", action="store_true", help="print the read-only collector script and exit")
+    ri.add_argument("--advisory", type=Path, help='JSON: {"id": "CVE-...", "component": "php", "fixed": {"8.1": "8.1.31"}, "unsupportedLines": ["7.4"]}')
+    ri.add_argument("--latest-tags", type=Path, help='JSON: newest patch per image line, {"php": {"8.2": "8.2.26"}}')
+    ri.add_argument("--eol-table", type=Path, help='JSON added to the built-in table, {"ubuntu": {"25.04": "2026-01-15"}}')
+    ri.add_argument("--today", help="YYYY-MM-DD (default: today)")
+    ri.add_argument("--image", default="php:{version}-fpm", help="migration image; {version} = fixed version, {line} = its line (e.g. wordpress:php{line}-fpm)")
+    ri.add_argument("--base-port", type=int, default=9100, help="first 127.0.0.1 port for new php-fpm containers")
+    ri.add_argument("--writable", action="append", default=[], help="folder under the site root the container may write (uploads, cache); everything else is mounted read-only")
+    hl = sub.add_parser("host-lock", parents=[ssh_parent], help="one agent session at a time on a production host")
+    hl.add_argument("action", choices=("acquire", "status", "release"))
+    hl.add_argument("--host", required=True, help='ssh target, or "local"')
+    hl.add_argument("--session", required=True, help="this agent session's id")
+    hl.add_argument("--ttl", type=int, default=3600, help="seconds the lock lasts without renewal")
+    hl.add_argument("--purpose", default="", help="what this session is changing (shown to other sessions)")
+    hl.add_argument("--force", action="store_true", help="release a lock held by another session (only after confirming it stopped)")
+    hl.add_argument("--recent-minutes", type=int, default=30)
+    hl.add_argument("--lock-path", default="/run/lock/maggie-agent-host.lock")
+    hl.add_argument("--watch", action="append", default=[], help="folders checked for recent changes (default systemd units, nginx, container units)")
+    for command in (ri, hl):
+        command.add_argument("--output", type=Path)
+    args = parser.parse_args(argv)
+    ssh_args = []
+    if args.ssh_key:
+        ssh_args += ["-i", os.path.expanduser(args.ssh_key)]
+    if args.ssh_port != "22":
+        ssh_args += ["-p", args.ssh_port]
+    try:
+        if args.command == "runtime-inventory":
+            if args.print_collector:
+                print(COLLECTOR)
+                return 0
+            if not args.evidence and not args.ssh:
+                raise ValueError("pass --evidence FILE or --ssh user@host")
+            text = args.evidence.read_text(encoding="utf-8", errors="replace") if args.evidence else collect_ssh(args.ssh, ssh_args)
+            table = {key: dict(value) for key, value in EOL.items()}
+            if args.eol_table:
+                for key, value in json.loads(args.eol_table.read_text(encoding="utf-8")).items():
+                    table.setdefault(key, {}).update(value)
+            report = inventory(text, json.loads(args.advisory.read_text(encoding="utf-8")) if args.advisory else None,
+                               json.loads(args.latest_tags.read_text(encoding="utf-8")) if args.latest_tags else {},
+                               date.fromisoformat(args.today) if args.today else date.today(), table, args.image, args.base_port, args.writable)
+        else:
+            report = host_lock(args.action, args.host, args.session, args.ttl, args.purpose, args.force, args.recent_minutes, args.lock_path, args.watch or WATCH, ssh_args)
+    except (OSError, ValueError, json.JSONDecodeError, subprocess.SubprocessError) as error:
+        print(f"BLOCKED: maggie deployment {args.command}: {error}", file=sys.stderr)
+        return 2
+    text = json.dumps(report, indent=2, ensure_ascii=False)
+    if args.output:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(text + "\n", encoding="utf-8")
+    print(text)
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())