@topy-ai/maggie 0.7.44 → 0.7.46

package/bundled-tools/clis/maggie_deployment.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import argparse
 import json
 import re
+import shlex
 import subprocess
 import sys
 from datetime import datetime, timezone
@@ -181,7 +182,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 +337,24 @@ 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"
         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
@@ -471,9 +582,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,6 +647,10 @@ 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("--retention-plan", action="store_true", help="create a read-only release prune candidate plan")
@@ -521,6 +665,17 @@ def main() -> int:
     parser.add_argument("--has-auth", action="store_true")
     args = parser.parse_args()
     try:
+        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 +704,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")

package/bundled-tools/clis/maggie_feedback.py

@@ -30,8 +30,15 @@ VERSION_RE = re.compile(r"\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?")
 SAFE_BATCH_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$")
 SAFE_ROUTE_RE = re.compile(r"^/[A-Za-z0-9._~!$&'()*+,;=:@%/?#-]{1,240}$")
 SAFE_EVIDENCE_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:/=-]{0,159}$")
+SAFE_FEEDBACK_ID_RE = re.compile(r"^fb-[A-Za-z0-9_-]{1,159}$")
 MAX_ROUTE_IDS = 20
 MAX_VALIDATION_EVIDENCE = 20
+MAX_EVIDENCE_REFERENCES = 20
+MAX_RELATIONSHIPS = 20
+MAX_GRAPH_NODES = 200
+MAX_GRAPH_EDGES = 300
+EVIDENCE_KINDS = {"test", "report", "screenshot", "command", "deployment", "issue", "commit", "artifact"}
+RELATION_KINDS = {"related", "same-run", "same-fingerprint", "duplicates", "validates", "remediates", "caused-by"}
 ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
 REPO_ROOT = Path(__file__).resolve().parents[2]
 
@@ -134,6 +141,64 @@ def safe_validation_evidence(values: object) -> list[str]:
     return sorted(set(result))
 
 
+def safe_evidence_references(values: object) -> list[dict]:
+    """Normalize bounded evidence pointers without copying artifacts or payloads."""
+    if not isinstance(values, list):
+        return []
+    result = []
+    for value in values[:MAX_EVIDENCE_REFERENCES]:
+        if isinstance(value, str):
+            if ":" not in value:
+                continue
+            kind, reference = value.split(":", 1)
+            status = "observed"
+        elif isinstance(value, dict):
+            kind = value.get("kind", "")
+            reference = value.get("ref", "")
+            status = value.get("status", "observed")
+        else:
+            continue
+        kind = safe_text(kind).lower()
+        reference = safe_text(reference)
+        status = safe_text(status).lower()
+        if kind not in EVIDENCE_KINDS or not SAFE_EVIDENCE_RE.fullmatch(reference):
+            continue
+        if status not in {"passed", "failed", "observed", "not-run", "unknown"}:
+            status = "unknown"
+        result.append({"kind": kind, "ref": reference, "status": status})
+    return sorted({(item["kind"], item["ref"], item["status"]): item for item in result}.values(),
+                  key=lambda item: (item["kind"], item["ref"], item["status"]))
+
+
+def safe_relationships(values: object) -> list[dict]:
+    """Normalize links to other safe IDs; never accept URLs or arbitrary payloads."""
+    if not isinstance(values, list):
+        return []
+    result = []
+    for value in values[:MAX_RELATIONSHIPS]:
+        if isinstance(value, str):
+            if "=" not in value:
+                continue
+            kind, target = value.split("=", 1)
+            confidence = "medium"
+        elif isinstance(value, dict):
+            kind = value.get("kind", "")
+            target = value.get("target", "")
+            confidence = value.get("confidence", "medium")
+        else:
+            continue
+        kind = safe_text(kind).lower()
+        target = safe_text(target)
+        confidence = safe_text(confidence).lower()
+        if kind not in RELATION_KINDS or not SAFE_EVIDENCE_RE.fullmatch(target):
+            continue
+        if confidence not in {"low", "medium", "high"}:
+            confidence = "medium"
+        result.append({"kind": kind, "target": target, "confidence": confidence})
+    return sorted({(item["kind"], item["target"], item["confidence"]): item for item in result}.values(),
+                  key=lambda item: (item["kind"], item["target"], item["confidence"]))
+
+
 def collect(args: argparse.Namespace) -> int:
     project = Path(args.project).resolve()
     report = load_json(Path(args.run_report)) if args.run_report else {}
@@ -171,6 +236,8 @@ def collect(args: argparse.Namespace) -> int:
     affected_cli = safe_text(getattr(args, "affected_cli", ""))
     route_ids = safe_route_ids(getattr(args, "route_ids", []))
     validation_evidence = safe_validation_evidence(getattr(args, "validation_evidence", []))
+    evidence = safe_evidence_references(getattr(args, "evidence", []))
+    relationships = safe_relationships(getattr(args, "relationships", []))
     context = {"projectFingerprint": project_fingerprint(project)}
     if args.allow_project_context and args.context_note:
         context["note"] = safe_text(args.context_note)
@@ -197,6 +264,8 @@ def collect(args: argparse.Namespace) -> int:
         "affectedCli": affected_cli,
         "routeIds": route_ids,
         "validationEvidence": validation_evidence,
+        "evidence": evidence,
+        "relationships": relationships,
         "attachments": [attachment(value) for value in args.screenshot],
         "environment": {"os": platform.system().lower(), "python": platform.python_version()},
         "privacy": {"secretsRedacted": True, "projectContextAllowed": bool(args.allow_project_context)},
@@ -226,7 +295,7 @@ def to_markdown(data: dict) -> str:
     lines += ["", "## Report", "", f"**Summary:** {data.get('summary') or 'Not provided'}", "", f"**Expected:** {data.get('expected') or 'Not provided'}", "", f"**Actual:** {data.get('actual') or 'Not provided'}", ""]
     if data.get("stepsToReproduce"):
         lines += ["**Steps to reproduce:**", ""] + [f"{index}. {step}" for index, step in enumerate(data["stepsToReproduce"], 1)] + [""]
-    lines += [f"**Fixed:** {'yes' if data.get('fixed') else 'no'}", f"**Resolution:** {data.get('resolution') or 'Not provided'}", f"**Validation:** {data.get('validation') or 'Not provided'}", "", "## Privacy", "", f"- Project context allowed: `{bool(data.get('privacy', {}).get('projectContextAllowed'))}`", f"- Attachments: `{len(data.get('attachments', []))}` metadata-only reference(s)", ""]
+    lines += [f"**Fixed:** {'yes' if data.get('fixed') else 'no'}", f"**Resolution:** {data.get('resolution') or 'Not provided'}", f"**Validation:** {data.get('validation') or 'Not provided'}", f"**Evidence references:** `{len(safe_evidence_references(data.get('evidence', [])))}`", f"**Relationships:** `{len(safe_relationships(data.get('relationships', [])))}`", "", "## Privacy", "", f"- Project context allowed: `{bool(data.get('privacy', {}).get('projectContextAllowed'))}`", f"- Attachments: `{len(data.get('attachments', []))}` metadata-only reference(s)", ""]
     return "\n".join(lines)
 
 
@@ -307,6 +376,8 @@ def collect_batch(args: argparse.Namespace) -> int:
         "affected_cli": safe_text(manifest.get("affectedCli")),
         "route_ids": safe_route_ids(manifest.get("routeIds", [])),
         "validation_evidence": safe_validation_evidence(manifest.get("validationEvidence", [])),
+        "evidence": safe_evidence_references(manifest.get("evidence", [])),
+        "relationships": safe_relationships(manifest.get("relationships", [])),
     }
     paths = []
     for index, item in enumerate(items):
@@ -337,11 +408,15 @@ def collect_batch(args: argparse.Namespace) -> int:
             "affected_cli": item.get("affectedCli") or shared["affected_cli"],
             "route_ids": item.get("routeIds", shared["route_ids"]),
             "validation_evidence": item.get("validationEvidence", shared["validation_evidence"]),
+            "evidence": item.get("evidence", shared["evidence"]),
+            "relationships": item.get("relationships", shared["relationships"]),
         }
         if not isinstance(values["reproduce"], list): values["reproduce"] = []
         if not isinstance(values["screenshot"], list): values["screenshot"] = []
         values["route_ids"] = safe_route_ids(values["route_ids"])
         values["validation_evidence"] = safe_validation_evidence(values["validation_evidence"])
+        values["evidence"] = safe_evidence_references(values["evidence"])
+        values["relationships"] = safe_relationships(values["relationships"])
         paths.append(collect(argparse.Namespace(**values)))
     print(json.dumps({"batchId": batch_id, "count": len(paths), "status": "drafts-created"}, ensure_ascii=False))
     return 0
@@ -380,6 +455,8 @@ def batch_review(args: argparse.Namespace) -> int:
             "validation": safe_text(data.get("validation")),
             "routeIds": safe_route_ids(data.get("routeIds", [])),
             "validationEvidence": safe_validation_evidence(data.get("validationEvidence", [])),
+            "evidence": safe_evidence_references(data.get("evidence", [])),
+            "relationships": safe_relationships(data.get("relationships", [])),
         })
     records.sort(key=lambda item: (item["index"] is None, item["index"] if isinstance(item["index"], int) else 0, item["feedbackId"]))
     expected_count = max(expected_sizes, default=len(records))
@@ -390,6 +467,39 @@ def batch_review(args: argparse.Namespace) -> int:
         if key:
             duplicate_groups.setdefault(key, []).append(item["feedbackId"])
     duplicates = [{"key": safe_text(key), "feedbackIds": ids} for key, ids in duplicate_groups.items() if len(ids) > 1]
+    graph_nodes = [{"id": item["feedbackId"], "kind": "feedback"} for item in records]
+    graph_edges = []
+    evidence_nodes = {}
+    for item in records:
+        for evidence in item["evidence"]:
+            evidence_key = f"{evidence['kind']}:{evidence['ref']}"
+            evidence_id = "evidence-" + hashlib.sha256(evidence_key.encode("utf-8")).hexdigest()[:16]
+            evidence_nodes.setdefault(evidence_id, {"id": evidence_id, "kind": "evidence", **evidence})
+            graph_edges.append({"from": item["feedbackId"], "to": evidence_id, "kind": "evidenced-by"})
+        for relationship in item["relationships"]:
+            target = relationship["target"]
+            target_id = target if SAFE_FEEDBACK_ID_RE.fullmatch(target) else "reference-" + hashlib.sha256(target.encode("utf-8")).hexdigest()[:16]
+            if not any(node["id"] == target_id for node in graph_nodes):
+                graph_nodes.append({"id": target_id, "kind": "related-reference"})
+            graph_edges.append({"from": item["feedbackId"], "to": target_id, "kind": relationship["kind"], "confidence": relationship["confidence"]})
+    graph_nodes.extend(evidence_nodes.values())
+    graph_nodes = graph_nodes[:MAX_GRAPH_NODES]
+    allowed_node_ids = {node["id"] for node in graph_nodes}
+    graph_edges = [edge for edge in graph_edges if edge["from"] in allowed_node_ids and edge["to"] in allowed_node_ids][:MAX_GRAPH_EDGES]
+    evidence_usage = {}
+    for item in records:
+        for evidence in item["evidence"]:
+            key = f"{evidence['kind']}:{evidence['ref']}"
+            evidence_usage.setdefault(key, []).append(item["feedbackId"])
+    remediation_suggestions = []
+    if duplicates:
+        remediation_suggestions.append("Review duplicate fingerprints or summaries and link one canonical remediation issue before implementation.")
+    if len(records) != expected_count:
+        remediation_suggestions.append("Collect the missing batch indexes before treating this batch as complete.")
+    if any(len(ids) > 1 for ids in evidence_usage.values()):
+        remediation_suggestions.append("Inspect shared evidence references for a common root cause and reuse one regression test where appropriate.")
+    if not any(item["evidence"] for item in records):
+        remediation_suggestions.append("Attach bounded test, report, screenshot, command, or deployment references before release review.")
     output = Path(args.output) if args.output else project / ".maggie" / "feedback" / "batches" / f"{batch_id}-review.json"
     if not output.is_absolute(): output = project / output
     report = {
@@ -403,6 +513,8 @@ def batch_review(args: argparse.Namespace) -> int:
         "phases": sorted({item["phase"] for item in records if item["phase"]}),
         "observations": records,
         "duplicates": duplicates,
+        "evidenceGraph": {"nodes": graph_nodes, "edges": graph_edges},
+        "remediationSuggestions": remediation_suggestions,
         "privacy": {"rawPayloadsIncluded": False, "localPathsIncluded": False, "secretsRedacted": True},
     }
     output.parent.mkdir(parents=True, exist_ok=True)
@@ -446,6 +558,8 @@ def main() -> int:
     collect_parser.add_argument("--affected-cli", default="")
     collect_parser.add_argument("--route-id", dest="route_ids", action="append", default=[])
     collect_parser.add_argument("--validation-evidence", dest="validation_evidence", action="append", default=[])
+    collect_parser.add_argument("--evidence-ref", dest="evidence", action="append", default=[], help="safe kind:reference pointer; no file contents are copied")
+    collect_parser.add_argument("--relationship", dest="relationships", action="append", default=[], help="safe relation=target pointer")
     batch_parser = sub.add_parser("batch")
     batch_parser.add_argument("--project", default=argparse.SUPPRESS)
     batch_parser.add_argument("--batch-file", required=True)

package/bundled-tools/clis/maggie_ops.py

@@ -16,6 +16,7 @@ from agent_runtime import preflight as agent_preflight
 from restart_gate import validate as validate_restart_gate
 from google_capabilities import validate_report as validate_google_capability_report
 from maggie_favicon import check_favicon
+from external_write import validate as validate_external_write
 
 
 REQUIRED_ROUTES = (
@@ -176,12 +177,40 @@ def command_google_capabilities(args: argparse.Namespace) -> int:
         "status": "passed" if result["passed"] else "failed",
         "report": str(output),
         "providerCount": len(result["providerResults"]),
+        "verifiedTargets": [
+            {
+                "provider": item["provider"],
+                "activeAccount": item["activeAccount"],
+                "target": item["target"],
+                "scopes": item["scopes"],
+            }
+            for item in result["providerResults"]
+        ],
         "failedChecks": result["errors"],
         "mutationsAllowed": False,
     }, indent=2, ensure_ascii=False))
     return 0 if result["passed"] else 1
 
 
+def command_external_write_gate(args: argparse.Namespace) -> int:
+    evidence = read_json(Path(args.evidence).resolve())
+    result = validate_external_write(evidence)
+    output = Path(args.output).resolve() if args.output else root(args) / ".maggie" / "external-write-readback.json"
+    write_json(output, result)
+    print(json.dumps({
+        "status": "passed" if result["passed"] else "failed",
+        "report": str(output),
+        "provider": result.get("provider"),
+        "resource": result.get("resource"),
+        "operation": result.get("operation"),
+        "idempotencyKey": result.get("idempotencyKey"),
+        "readback": result.get("readback"),
+        "failedChecks": result["errors"],
+        "mutation": "not executed",
+    }, indent=2, ensure_ascii=False))
+    return 0 if result["passed"] else 1
+
+
 def command_favicon_check(args: argparse.Namespace) -> int:
     result = check_favicon(args.origin, args.declared_url, args.timeout)
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -210,6 +239,10 @@ def main() -> int:
     google.add_argument("--report", required=True)
     google.add_argument("--output")
     google.set_defaults(func=command_google_capabilities)
+    external_write = sub.add_parser("external-write-gate", help="validate idempotent provider write/readback evidence")
+    external_write.add_argument("--evidence", required=True)
+    external_write.add_argument("--output")
+    external_write.set_defaults(func=command_external_write_gate)
     favicon = sub.add_parser("favicon-check", help="fetch /favicon.ico and the declared icon to verify behaviour")
     favicon.add_argument("--origin", required=True)
     favicon.add_argument("--declared-url")