@topy-ai/maggie 0.7.45 → 0.7.47

package/bundled-skills/maggie-deployment/SKILL.md

@@ -219,6 +219,12 @@ files and the application remain separated (`maggie-deploy` versus
 Install and review that narrow sudoers policy on the host before executing a
 runner.
 
+Generated release runners include their Maggie version and a template
+fingerprint. VPS preflight checks runners under `.maggie/deployment/` and warns
+when they are unmarked or stale; use `--check-runner PATH` for a runner stored
+elsewhere. Regenerate from the reviewed VPS plan, inspect the diff, and replace
+the checked-in runner only after review.
+
 VPS plans include a bounded retention policy: keep two immutable releases,
 preserve the `current` target and rollback target, and review prune candidates
 before any operator executes cleanup. Generate a read-only candidate report:
@@ -301,28 +307,41 @@ output/state artifact and must never be used as the provider source argument.
 When validating a project schedule, pass `--project` so the URL is compared
 exactly with `.maggie/booking/services.json` `sourceUrl`.
 
-For a single read-only staging release gate, run. This gate also requires
-explicit editorial approval for all launch category copy; rendered draft
-evidence is not publication approval:
+For a single read-only staging release gate, first declare the project's release
+surface in `.maggie/release-profile.json`. The manifest is the source of truth;
+Maggie does not infer Booking, MaggieDash, migration, analytics, service
+catalogue, or editorial gates from incidental files. A minimal public Astro
+site can use:
+
+```json
+{
+  "schemaVersion": "maggie-release-profile.v1",
+  "profile": "public-astro",
+  "projectType": "astro",
+  "capabilities": ["deployment"]
+}
+```
+
+Add `migration`, `maggiedash-health`, `schedule`, `analytics-contract`,
+`service-facts`, `editorial-review`, or `durable-site-evidence` only when that
+project actually owns the corresponding artifact. For a single read-only
+staging release gate, run:
 
 ```bash
 maggie tool maggie_release.py /path/to/project \
+  --profile /path/to/project/.maggie/release-profile.json \
   --environment staging --target vps-with-cloudflare-dns \
   --base-url https://staging.example.com
 ```
 
-If `.maggie/scenario-manifest.json` or `.maggie/qa-runs/` exists, the same
-preflight consumes the latest matching `maggie qa` run for the requested
-environment (and `--base-url`, when supplied). It blocks when a scenario is
-not passed, has no browser-adapter evidence, or the matching run is missing.
-Projects without scenario QA report `not-configured`; Maggie does not run the
-browser itself.
-
-This aggregates deployment, migration, provider-health, schedule, analytics,
-service-fact, editorial approval, durable SEO/route/category evidence,
-MaggieDash schema compatibility, and live runtime security-header checks. It writes
-`.maggie/release-preflight.json`; a failed gate blocks release. It never
-deploys, migrates, publishes, or sends provider requests.
+If `scenario-qa` is declared, the preflight consumes the latest matching
+`maggie qa` run for the requested environment (and `--base-url`, when
+supplied). It blocks when a scenario is not passed, has no browser-adapter
+evidence, or the matching run is missing. The report records every undeclared
+optional gate as `skipped`, so a public site is not blocked by Booking- or
+MaggieDash-only evidence. It writes `.maggie/release-preflight.json`; a failed
+gate blocks release. It never deploys, migrates, publishes, or sends provider
+requests.
 
 Generate a repeatable VPS runner as part of the plan. A deploy step that exists
 only in an operator's shell history is not a release contract:
@@ -338,6 +357,27 @@ Review the generated runner before execution. Its order is install → typecheck
 → migrate → build → carry agent state → switch → restart → verify → prune;
 retention keeps the current release and one rollback candidate.
 
+Before writing a VPS plan or running the release gate, validate the real
+least-privilege deploy account. This check is read-only: it verifies SSH access,
+write permission for both the release root and `releases/`, and the exact
+non-interactive systemd allowlist. A failed check does not create the plan or
+runner:
+
+```bash
+maggie deployment --verify-deployer \
+  --deployer-host "$DEPLOY_SERVER_IP" \
+  --deployer-user "$DEPLOY_SERVER_SSH_USER" \
+  --release-root /var/www/example \
+  --service example \
+  --output .maggie/deployment/deployer-delegation.json
+```
+
+For a VPS `maggie release`, this evidence is required at
+`.maggie/deployment/deployer-delegation.json` (or pass
+`--deployer-evidence`). The generated runner waits for bounded transient
+`000/502/503/504` startup responses after restart, while returning a clear
+failure immediately for permanent HTTP responses.
+
 Production additionally requires `docs/deployment-rollback-smoke.json` with
 `passed: true`, `environment: production`, and `testedAt`. For an upgrade it
 must include a non-empty `previousRelease`. For the first production release,

package/bundled-skills/maggie-feedback/SKILL.md

@@ -30,10 +30,29 @@ maggie feedback --project . collect \
 maggie feedback preview .maggie/feedback/<feedback-id>.json --format markdown
 ```
 
-The draft is written to `.maggie/feedback/`. It contains the Maggie version,
+The draft is written to `.maggie/feedback/`. List local drafts with
+`maggie feedback list --project .`; `--project` works before or after the
+subcommand. A draft contains the Maggie version,
 skill, run ID, phase, error fingerprint, expected/actual result, reproduction
 steps, resolution, validation, and metadata-only screenshot references.
 
+Attach bounded, privacy-safe evidence and relationships when a maintainer will
+need to connect a report to a test, deployment, issue, or related run. Only
+identifiers are stored; file contents, logs, credentials, and local paths are
+never copied:
+
+```bash
+maggie feedback collect --project . --summary "Adapter unavailable" \
+  --evidence-ref test:browser-capability:passed \
+  --evidence-ref report:browser-capability:v1 \
+  --relationship same-run=clone-001
+```
+
+Evidence references are bounded and normalized into the
+`maggie-feedback-evidence-bundle.v1` contract. The accepted kinds are
+`test`, `report`, `screenshot`, `command`, `deployment`, `issue`, `commit`,
+and `artifact`; relationships connect safe IDs such as feedback or run IDs.
+
 If a draft is marked fixed with `--fixed` (or the supplied run report says
 `fixed`), both `--resolution` and `--validation` are required. Feedback text
 also scrubs common POSIX/home/temp and Windows absolute paths by default while
@@ -78,6 +97,12 @@ This writes `.maggie/feedback/batches/<batch-id>-review.json` under the
 duplicate fingerprints/summaries, while retaining only redacted observations;
 review the aggregate and each draft before submitting.
 
+Batch review also emits a bounded `evidenceGraph` and
+`remediationSuggestions`. The graph links feedback IDs to evidence IDs and
+safe related references, while suggestions flag duplicate fingerprints,
+missing batch indexes, shared evidence, or a batch with no validation
+references. These are review aids, not automatic issue or memory writes.
+
 Example:
 
     {

package/bundled-skills/maggie-memory/SKILL.md

@@ -29,7 +29,7 @@ truth, content state, or audit log.
 
 ## Workflow
 
-1. At the start of a relevant workflow, run `maggie memory context --project . --skill <skill>` and load only matching active items.
+1. At the start of a relevant workflow, run `maggie memory context --project . --skill <skill>` and load only matching active project-scope items. Use `--include-shared` only after explicit opt-in.
 2. Show material preferences, conventions, and prevention lessons before making a decision.
 3. When the user gives a durable preference or confirms a repaired pitfall, save it explicitly as `candidate` or `active` with scope and evidence.
 4. Record every meaningful failure with `record-error`; include a stable fingerprint, resolution, and validation result when fixed.
@@ -45,6 +45,15 @@ truth, content state, or audit log.
 preserving project scope. Expired active items remain inspectable through
 explicit status listing but are excluded from normal context.
 
+Project-scope `maggie init` creates the repository's `.maggie/memory/` store.
+Repeated initialization preserves existing memory files without rewriting
+their contents or timestamps. A context response distinguishes a ready store
+from an uninitialized project; the shared memory hook falls back to the
+installed CLI when local Python tools are absent.
+
+Project `context`, `search`, and `list` read only project-scope items by
+default. `--include-shared` explicitly opts into user/workspace-scoped entries.
+
 ```bash
 maggie memory init --project .
 maggie memory context --project . --skill maggie-clone

package/bundled-skills/maggie-ops/SKILL.md

@@ -88,6 +88,14 @@ maggie ops google-capabilities --project . \
   --report .maggie/google-capability-input.json
 ```
 
+The input must use `maggie-google-capability-report.v2`: each row records the
+redacted active account, the selected target (`property`, `container`,
+`customer`, `project`, or `site`), and the exact scopes. Both account and target
+must be explicitly verified, and `target.id` must equal `resource`. The command
+prints these safe identifiers and scopes before any separate provider adapter
+is allowed to perform a write. A v1 report is rejected because it cannot prove
+that the browser/session is on the intended Google account and property.
+
 The result separates `read`, `report`, `edit`, and `publish` for each
 provider/resource. Write and publish remain `not_tested` until the operator
 explicitly confirms the exact mutation and a successful read-back is captured.
@@ -164,6 +172,20 @@ Every mutation must validate the session, role, resource ownership/project
 scope, input schema, legal state transition, and idempotency/correlation key.
 Record actor, timestamp, previous state, next state, reason, and result.
 
+For a GA4/GTM or other Google provider write, validate a hash-only
+write/readback bundle before treating the operation as complete:
+
+```bash
+maggie ops external-write-gate --project . \
+  --evidence .maggie/external-write-readback-input.json \
+  --output .maggie/external-write-readback.json
+```
+
+The bundle requires one stable idempotency key across bounded retries, explicit
+confirmation, successful readback fingerprints, an empty duplicate list, and
+an empty orphaned-workspace list. It never stores provider payloads; an
+incomplete or mismatched readback blocks the release gate.
+
 ### Operate
 
 Use the dashboard or API to perform an explicitly requested operation. Show an

package/bundled-skills/maggie-seo-geo/SKILL.md

@@ -125,7 +125,10 @@ maggie analytics release-gate --project . --environment staging \
 
 Use `contracts/maggie-seo/gsc-readiness-v1.schema.json` as the evidence
 boundary. Credentials and mutation scopes remain host-owned; a passing local
-contract is not proof of property ownership or live readback.
+contract is not proof of property ownership or live readback. If a GA4/GTM
+write is part of the workflow, also pass hash-only
+`.maggie/external-write-readback.json` evidence to the analytics release gate;
+duplicate or orphaned provider objects fail closed.
 
 ## Freeze and compare a reviewed site
 

package/bundled-tools/clis/maggie_analytics.py

@@ -13,6 +13,7 @@ from urllib.parse import urlsplit
 import sys
 sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "runtime"))
 from analytics_traffic import audit_events  # noqa: E402
+from external_write import validate as validate_external_write  # noqa: E402
 
 
 GA4_ID = re.compile(r"^G-[A-Z0-9]+$", re.I)
@@ -122,6 +123,12 @@ def release_gate(args: argparse.Namespace) -> int:
             errors.append("gsc-evidence-schema")
     elif args.require_gsc:
         errors.append("gsc-evidence-required")
+    if args.write_readback:
+        write_readback, write_errors = load_json(Path(args.write_readback).resolve(), "external write readback")
+        errors.extend(write_errors)
+        write_result = validate_external_write(write_readback or {})
+        check("external-write-readback", write_result["passed"], "idempotency, readback, duplicate, and cleanup evidence", checks)
+        errors.extend(write_result["errors"])
     if browser:
         check("browser-schema", browser.get("schemaVersion") == "maggie-analytics-browser.v1", "versioned browser evidence", checks)
         check("browser-render", browser.get("passed") is True and isinstance(browser.get("routes"), list) and bool(browser["routes"]), "routes rendered without a browser failure", checks)
@@ -191,6 +198,7 @@ def main() -> int:
     parser.add_argument("--smoke-report", help="production smoke evidence for release-gate")
     parser.add_argument("--gsc-evidence", help="versioned GSC readiness evidence for release-gate")
     parser.add_argument("--require-gsc", action="store_true", help="require GSC readiness evidence in release-gate")
+    parser.add_argument("--write-readback", help="hash-only external write/readback evidence for release-gate")
     parser.add_argument("--events", help="redacted JSON array of analytics events for traffic-audit")
     args = parser.parse_args()
     if args.command == "gsc-readiness":

package/bundled-tools/clis/maggie_browser_audit.py

@@ -10,6 +10,7 @@ from urllib.parse import urlparse
 RUNTIME = Path(__file__).resolve().parents[1] / "runtime"
 sys.path.insert(0, str(RUNTIME))
 from browser_behavior import validate_samples
+from browser_capability import discover_browser_adapter, require_browser_adapter
 from localization_runner import checkpoint
 
 
@@ -108,10 +109,17 @@ def run_interactions(call, steps: list[dict]) -> list[dict]:
 def audit(args):
     if urlparse(args.url).scheme not in {"http", "https", "file"}:
         raise ValueError("URL must use http, https or file")
-    if not args.required:
+    if not args.required and not args.check_browser:
         raise ValueError("at least one --required selector is necessary")
     output = args.output.resolve()
     output.mkdir(parents=True, exist_ok=True)
+    capability = discover_browser_adapter(args.browse)
+    capability_path = args.capability_report.resolve() if args.capability_report else output / "browser-capability.json"
+    checkpoint(capability_path, capability)
+    if args.check_browser:
+        print(json.dumps(capability, indent=2))
+        return 0 if capability["status"] == "ready" else 1
+    require_browser_adapter(args.browse)
     interactions = load_interactions(args.interactions)
     def call(*command):
         result = subprocess.run([str(args.browse), *command], capture_output=True, text=True, timeout=45)
@@ -120,7 +128,8 @@ def audit(args):
         return result.stdout
     report = {"schemaVersion": "maggie-browser-audit.v1", "url": args.url,
               "passed": False, "viewports": [], "evidence": "browser-captured",
-              "interactionManifest": str(args.interactions.resolve()) if args.interactions else None}
+              "interactionManifest": str(args.interactions.resolve()) if args.interactions else None,
+              "browserCapability": str(capability_path)}
     try:
         for index, viewport in enumerate(args.viewport or ["390x844", "768x1024", "1440x900"]):
             width, height = [int(value) for value in viewport.split("x")]
@@ -158,6 +167,8 @@ def main():
     parser.add_argument("url")
     parser.add_argument("--browse", type=Path, required=True)
     parser.add_argument("--output", type=Path, required=True, help="new directory for evidence")
+    parser.add_argument("--capability-report", type=Path, help="write the redacted browser adapter capability report here")
+    parser.add_argument("--check-browser", action="store_true", help="only check adapter capability; do not navigate or write page evidence")
     parser.add_argument("--viewport", action="append")
     parser.add_argument("--required", action="append", default=[])
     parser.add_argument("--sticky", action="append", default=[])

package/bundled-tools/clis/maggie_deployment.py

@@ -3,8 +3,12 @@
 from __future__ import annotations
 
 import argparse
+import hashlib
+import inspect
 import json
+import os
 import re
+import shlex
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -181,7 +185,103 @@ def worker_secret_preflight_main(argv: list[str]) -> int:
     return 0 if result["passed"] else 1
 
 
-def preflight(project: Path, target: str, environment: str) -> dict:
+def deployer_delegation_preflight(
+    host: str,
+    user: str,
+    release_root: str,
+    service: str,
+    ssh_command: list[str] | None = None,
+) -> dict:
+    """Read-only SSH check for release-directory and systemd delegation."""
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.:-]{0,253}", host):
+        raise ValueError("deployer host must be a hostname, address, or IPv6-safe token")
+    if not re.fullmatch(r"[a-z_][a-z0-9_-]{0,31}\$?", user):
+        raise ValueError("deployer user must be a safe local account name")
+    if not release_root.startswith("/") or "\n" in release_root or "\r" in release_root:
+        raise ValueError("release root must be an absolute path without newlines")
+    if not re.fullmatch(r"[A-Za-z0-9_.@-]+", service):
+        raise ValueError("service must contain only safe systemd name characters")
+
+    root = release_root.rstrip("/") or "/"
+    releases = f"{root}/releases" if root != "/" else "/releases"
+    remote_script = "\n".join((
+        "set -eu",
+        f"test -d {shlex.quote(root)} && test -w {shlex.quote(root)}",
+        f"test -d {shlex.quote(releases)} && test -w {shlex.quote(releases)}",
+        f"sudo -n -l /bin/systemctl restart {shlex.quote(service)} >/dev/null 2>&1",
+        f"sudo -n -l /bin/systemctl is-active {shlex.quote(service)} >/dev/null 2>&1",
+    )) + "\n"
+    command = list(ssh_command or ["ssh"])
+    command.extend(["-o", "BatchMode=yes", "-o", "ConnectTimeout=8", f"{user}@{host}", "sh", "-s"])
+    try:
+        completed = subprocess.run(command, input=remote_script, capture_output=True, text=True, check=False, timeout=20)
+    except (OSError, subprocess.SubprocessError) as error:
+        return {
+            "schemaVersion": "maggie-deployment-delegation.v1",
+            "host": host,
+            "user": user,
+            "releaseRoot": root,
+            "service": service,
+            "state": "transient",
+            "passed": False,
+            "checks": {},
+            "errors": [f"SSH delegation check could not start: {type(error).__name__}"],
+            "mutation": "not executed",
+        }
+    stderr = (completed.stderr or "").lower()
+    transient = completed.returncode in {124, 255} or any(marker in stderr for marker in (
+        "timed out", "connection refused", "connection reset", "no route", "could not resolve", "temporary failure",
+    ))
+    state = "passed" if completed.returncode == 0 else "transient" if transient else "failed"
+    return {
+        "schemaVersion": "maggie-deployment-delegation.v1",
+        "host": host,
+        "user": user,
+        "releaseRoot": root,
+        "service": service,
+        "state": state,
+        "passed": completed.returncode == 0,
+        "checks": {
+            "sshConnection": completed.returncode == 0,
+            "releaseRootWritable": completed.returncode == 0,
+            "releasesDirectoryWritable": completed.returncode == 0,
+            "sudoSystemctlRestart": completed.returncode == 0,
+            "sudoSystemctlStatus": completed.returncode == 0,
+        },
+        "errors": [] if completed.returncode == 0 else [
+            "deploy-user delegation check is transient; retry after SSH/host readiness" if transient
+            else "deploy-user cannot write the release directory or use the exact systemd allowlist"
+        ],
+        "mutation": "not executed",
+    }
+
+
+def validate_deployer_delegation(value: object, expected_root: str | None = None, expected_service: str | None = None) -> dict:
+    if not isinstance(value, dict):
+        return {"passed": False, "state": "failed", "errors": ["delegation evidence must be an object"]}
+    errors: list[str] = []
+    if value.get("schemaVersion") != "maggie-deployment-delegation.v1":
+        errors.append("delegation evidence schemaVersion is unsupported")
+    if value.get("state") != "passed" or value.get("passed") is not True:
+        errors.append("deploy-user delegation evidence is not passed")
+    if expected_root and value.get("releaseRoot") != expected_root.rstrip("/"):
+        errors.append("delegation releaseRoot does not match the deployment plan")
+    if expected_service and value.get("service") != expected_service:
+        errors.append("delegation service does not match the deployment plan")
+    checks = value.get("checks") if isinstance(value.get("checks"), dict) else {}
+    for name in ("sshConnection", "releaseRootWritable", "releasesDirectoryWritable", "sudoSystemctlRestart", "sudoSystemctlStatus"):
+        if checks.get(name) is not True:
+            errors.append(f"delegation check is not passed: {name}")
+    return {"passed": not errors, "state": "passed" if not errors else "failed", "errors": errors}
+
+
+def preflight(
+    project: Path,
+    target: str,
+    environment: str,
+    require_deployer: bool = False,
+    delegation_evidence: Path | None = None,
+) -> dict:
     package_path = project / "package.json"
     package = json.loads(package_path.read_text(encoding="utf-8")) if package_path.exists() else {}
     scripts = package.get("scripts") or {}
@@ -240,10 +340,27 @@ def preflight(project: Path, target: str, environment: str) -> dict:
         data_required = bool(migration.get("dataDependencies"))
         data_checkpoint = validate_data_checkpoint(data_path) if data_path.exists() else {"passed": not data_required, "declared": False, "errors": ["data-release.json is required for a data-dependent release"] if data_required else []}
         retention_ok = bool(plan.get("retention", {}).get("keep") in (2, 3, 4, 5) and plan.get("retention", {}).get("prune") and plan.get("retention", {}).get("preserve"))
-        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "release_retention_policy": retention_ok, "data_release_checkpoint": data_checkpoint["passed"], "remote_verification_pending": True, "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
+        delegation = {"passed": True, "state": "not-required", "errors": []}
+        delegation_path = delegation_evidence or project / ".maggie" / "deployment" / "deployer-delegation.json"
+        if require_deployer:
+            try:
+                delegation_value = json.loads(delegation_path.read_text(encoding="utf-8"))
+            except (OSError, json.JSONDecodeError) as error:
+                delegation_value = {}
+                delegation = {"passed": False, "state": "inconclusive", "errors": [f"delegation evidence is unavailable: {error}"]}
+            else:
+                delegation = validate_deployer_delegation(delegation_value, plan.get("release_root"), plan.get("service"))
+                delegation["path"] = str(delegation_path)
+        result["checks"].update({"node_runtime_declared": bool(package.get("engines", {}).get("node") or package.get("dependencies", {}).get("astro")), "start_command_or_runtime": "start" in scripts or "preview" in scripts, "stateless_or_migration_plan": True, "release_layout_declared": True, "rollback_command_declared": True, "release_retention_policy": retention_ok, "data_release_checkpoint": data_checkpoint["passed"], "remote_verification_pending": not delegation["passed"], "deployer_delegation": delegation["passed"], "release_plan_artifact": bool(plan_path and plan.get("release_layout") and plan.get("current_release")), "systemd_artifact": bool(systemd_text and "ExecStart=" in systemd_text and "EnvironmentFile=" in systemd_text and "NoNewPrivileges=true" in systemd_text), "nginx_artifact": bool(nginx_text and "proxy_pass" in nginx_text and "server_name" in nginx_text), "deployment_artifacts_secret_free": secret_free, "rollback_evidence": rollback_passed if environment == "production" else True})
+        result["delegation"] = delegation
         result["vps"] = {"runtime":"Node.js standalone","reverseProxy":"Nginx","processManager":"systemd","releaseLayout":"/var/www/<site>/releases/<release> + current symlink","dns":"Cloudflare DNS or registrar DNS; verify apex and www separately","remoteCommands":["npm ci","npm run build","systemctl restart <service>","systemctl is-active <service>","curl -fsS https://<domain>/robots.txt","curl -fsS https://<domain>/sitemap.xml"],"handoverFields":["host","sshUser","domain","service","release","previousRelease","nginxConfig","migrationVersion","verification","rollback"]}
         result["next_action"] = "review VPS host, SSH user, domain/DNS, systemd service, Nginx config, release path, migrations, and rollback owner before execute"
+        runners = sorted(deployment_dir.rglob("release-runner.sh")) if deployment_dir.exists() else []
+        result["release_runners"] = [release_runner_status(path) for path in runners[:25]]
+        result["warnings"] = [f"generated release runner is stale or unmarked: {item['path']}" for item in result["release_runners"] if item["status"] == "stale"]
         result["blocking_checks"] = ["package_manifest", "build_command", "env_example", "node_runtime_declared", "start_command_or_runtime", "stateless_or_migration_plan", "release_layout_declared", "rollback_command_declared", "release_retention_policy", "data_release_checkpoint", "release_plan_artifact", "systemd_artifact", "nginx_artifact", "deployment_artifacts_secret_free", "rollback_evidence"]
+        if require_deployer:
+            result["blocking_checks"].append("deployer_delegation")
     else:
         result["blocking_checks"] = ["package_manifest", "build_command", "env_example"]
     return result
@@ -438,15 +555,51 @@ WantedBy=multi-user.target
     (output_dir / f"{domain}.conf").write_text(nginx, encoding="utf-8")
 
 
+def release_runner_generator() -> dict[str, str]:
+    version = os.environ.get("MAGGIE_VERSION", "").strip()
+    if not version:
+        version_file = Path(__file__).resolve().parents[2] / "VERSION"
+        try:
+            version = version_file.read_text(encoding="utf-8").strip()
+        except OSError:
+            version = "unknown"
+    source = inspect.getsource(release_runner).encode("utf-8")
+    return {"version": version, "fingerprint": hashlib.sha256(source).hexdigest()[:16]}
+
+
+def release_runner_status(path: Path) -> dict:
+    try:
+        content = path.read_text(encoding="utf-8", errors="replace")
+    except OSError as error:
+        return {"path": str(path), "status": "stale", "reason": f"runner cannot be read: {error}", "refresh": "Regenerate from the reviewed VPS plan and inspect the diff."}
+    match = re.search(r"^# Maggie release runner: generator=([^ ]+) template=([a-f0-9]{16})$", content, re.MULTILINE)
+    current = release_runner_generator()
+    if not match:
+        return {"path": str(path), "status": "stale", "reason": "runner has no generator version/fingerprint", "currentGenerator": current, "refresh": "Regenerate from the reviewed VPS plan and inspect the diff before replacing this file."}
+    generated = {"version": match.group(1), "fingerprint": match.group(2)}
+    stale = generated != current
+    return {
+        "path": str(path),
+        "status": "stale" if stale else "current",
+        "generatedBy": generated,
+        "currentGenerator": current,
+        "reason": "runner generator version or template fingerprint has changed" if stale else "runner matches the current generator",
+        "refresh": "Regenerate from the reviewed VPS plan and inspect the diff before replacing this file." if stale else "",
+    }
+
+
 def release_runner(plan: dict) -> str:
     """Render the ordered, reviewable VPS runner for one release."""
     root = plan["release_root"]
     service = plan["service"]
     domain = plan["domain"]
     current = plan["current_release"]
+    generator = release_runner_generator()
     return f'''#!/usr/bin/env bash
 set -euo pipefail
 
+# Maggie release runner: generator={generator["version"]} template={generator["fingerprint"]}
+
 # Migration precedes the symlink flip; later releases carry agent state.
 : "${{RELEASE_ID:?set RELEASE_ID to an immutable release name}}"
 RELEASE_KIND="${{RELEASE_KIND:-upgrade}}"
@@ -471,9 +624,38 @@ if [ -d "$CURRENT/.claude" ]; then cp -a "$CURRENT/.claude" "$RELEASE/.claude";
 
 ln -sfn "$RELEASE" "$CURRENT"
 sudo -n /bin/systemctl restart "{service}"
-sudo -n /bin/systemctl is-active --quiet "{service}"
-curl -fsS "https://{domain}/robots.txt" >/dev/null
-curl -fsS "https://{domain}/sitemap.xml" >/dev/null
+
+# A restarted service can be healthy at the origin before Nginx/Cloudflare is
+# ready. Retry only bounded transient states; fail immediately on permanent
+# HTTP responses so an outage is not hidden as a startup delay.
+wait_for_active() {{
+  local attempt
+  for attempt in $(seq 1 12); do
+    if sudo -n /bin/systemctl is-active --quiet "{service}"; then return 0; fi
+    if [ "$attempt" -lt 12 ]; then sleep 2; fi
+  done
+  echo "permanent service readiness failure: {service}" >&2
+  return 1
+}}
+wait_for_http() {{
+  local url="$1" attempt status
+  for attempt in $(seq 1 12); do
+    status="$(curl --silent --show-error --output /dev/null --write-out '%{{http_code}}' "$url" 2>/dev/null || printf '000')"
+    case "$status" in
+      2??|3??) return 0 ;;
+      000|502|503|504)
+        if [ "$attempt" -lt 12 ]; then sleep 2; continue; fi
+        echo "transient readiness exhausted: $url returned $status" >&2
+        return 1 ;;
+      *)
+        echo "permanent readiness failure: $url returned $status" >&2
+        return 1 ;;
+    esac
+  done
+}}
+wait_for_active
+wait_for_http "https://{domain}/robots.txt"
+wait_for_http "https://{domain}/sitemap.xml"
 
 # Keep current plus one rollback candidate, and prune only after health checks.
 mapfile -t RELEASES < <(find "$RELEASE_ROOT/releases" -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | cut -d' ' -f2-)
@@ -507,8 +689,13 @@ def main() -> int:
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
     parser.add_argument("--node-port", type=int, required=False, default=None, help="unused host port; required with --vps-plan")
     parser.add_argument("--deployer-user", default="maggie-deploy", help="dedicated least-privilege SSH/deploy account")
+    parser.add_argument("--deployer-host", help="SSH host for --verify-deployer")
+    parser.add_argument("--verify-deployer", action="store_true", help="run a read-only SSH delegation check before writing VPS artifacts")
+    parser.add_argument("--require-deployer", action="store_true", help="require passed delegation evidence during deployment preflight")
+    parser.add_argument("--deployer-evidence", help="delegation evidence JSON; defaults to .maggie/deployment/deployer-delegation.json")
     parser.add_argument("--plan-dir", help="directory for generated VPS artifacts")
     parser.add_argument("--runner-output", help="write a reviewable ordered VPS release runner")
+    parser.add_argument("--check-runner", help="read-only check of a generated runner's Maggie version and template fingerprint")
     parser.add_argument("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
     parser.add_argument("--current-link", help="current symlink for --retention-plan")
     parser.add_argument("--keep-releases", type=int, default=2)
@@ -521,6 +708,21 @@ def main() -> int:
     parser.add_argument("--has-auth", action="store_true")
     args = parser.parse_args()
     try:
+        if args.check_runner:
+            report = release_runner_status(Path(args.check_runner).expanduser().resolve())
+            print(json.dumps(report, indent=2, ensure_ascii=False))
+            return 0
+        if args.verify_deployer:
+            if not args.deployer_host:
+                parser.error("--deployer-host is required with --verify-deployer")
+            delegation = deployer_delegation_preflight(args.deployer_host, args.deployer_user, args.release_root, args.service)
+            if args.output:
+                output = Path(args.output).resolve()
+                output.parent.mkdir(parents=True, exist_ok=True)
+                output.write_text(json.dumps(delegation, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+            print(json.dumps(delegation, indent=2, ensure_ascii=False))
+            if not delegation["passed"]:
+                return 1
         if args.vps_plan:
             if not args.domain:
                 parser.error("--domain is required with --vps-plan")
@@ -549,7 +751,13 @@ def main() -> int:
             result = verify_infrastructure(Path(args.units_dir).resolve() if args.units_dir else None, args.service, args.timer)
             print(json.dumps(result, indent=2, ensure_ascii=False))
             return 0 if result["passed"] else 1
-        result = preflight(Path(args.project).resolve(), args.target, args.environment)
+        result = preflight(
+            Path(args.project).resolve(),
+            args.target,
+            args.environment,
+            args.require_deployer,
+            Path(args.deployer_evidence).expanduser().resolve() if args.deployer_evidence else None,
+        )
         if args.output:
             Path(args.output).parent.mkdir(parents=True, exist_ok=True)
             Path(args.output).write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")