@topy-ai/maggie 0.7.26 → 0.7.28

package/bundled-skills/maggie-service-booking/SKILL.md

@@ -7,6 +7,25 @@ metadata:
 
 # Maggie Service Booking
 
+## Bounded worker and resolver evidence
+
+Before enabling provider crawling or URL resolution, validate sanitized host
+evidence. These checks keep queue depth, leases, concurrency, timeouts,
+retries, cancellation cleanup, and worker health explicit:
+
+```bash
+maggie service worker-health --project . \
+  --evidence .maggie/booking/worker-health-input.json
+maggie service resolver-audit --project . \
+  --evidence .maggie/booking/resolver-input.json
+```
+
+The worker report uses `maggie-booking-worker-health.v1`. Resolver outcomes are
+limited to `resolved`, `resolved-no-menu`, `not-found`, `blocked`, `timeout`,
+and `unavailable`; resolved outcomes require a public canonical HTTPS URL and
+safe evidence IDs. Raw provider responses, credentials, logs, and request
+bodies are never copied into the reports.
+
 Route matching evidence must come from the route source's actual import
 statements. The shared resolver in `tools/runtime/route_imports.py` resolves
 relative imports and records a component fingerprint; it never selects a

package/bundled-tools/clis/maggie.py

@@ -426,8 +426,29 @@ def command_api_lifecycle(args: argparse.Namespace) -> int:
             "total_posts", "matchedPosts", "matched_posts", "eligible",
             "unmatched", "queued", "accepted", "created", "updated",
             "skipped", "removed", "nextCursor", "next_cursor",
+            "message", "error", "quota_exhausted", "quotaExhausted",
+            "quotaDailyRemaining", "quota_daily_remaining",
+            "quotaMonthlyRemaining", "quota_monthly_remaining",
         )
-        summary = {key: value[key] for key in allowed if key in value and isinstance(value[key], (str, int, float, bool, type(None)))}
+        summary = {}
+        for key in allowed:
+            if key not in value or not isinstance(value[key], (str, int, float, bool, type(None))):
+                continue
+            item = value[key]
+            if key in {"message", "error"} and isinstance(item, str):
+                item = " ".join(item.split())[:300]
+            summary[key] = item
+        quota = value.get("quota")
+        if isinstance(quota, dict):
+            quota_summary = {}
+            for window_name, window in quota.items():
+                if not isinstance(window, dict) or not isinstance(window.get("remaining"), int):
+                    continue
+                quota_summary[str(window_name)] = {"remaining": window["remaining"]}
+            if quota_summary:
+                summary["quota"] = quota_summary
+        if value.get("quota_exhausted") is True or value.get("quotaExhausted") is True:
+            summary["effective_delivery_remaining"] = 0
         items = value.get("items")
         if isinstance(items, list):
             summary["item_count"] = len(items)
@@ -639,6 +660,13 @@ def interview_value(key: str, question: str, current: str, choices: list[str]) -
 def command_bootstrap_interview(args: argparse.Namespace) -> int:
     root = Path(args.project).resolve()
     analysis = detect(root)
+    if not args.non_interactive and not sys.stdin.isatty():
+        print(
+            "NON_INTERACTIVE_REQUIRED: stdin is not interactive; use --non-interactive "
+            "--answers-file answers.json --confirm after reviewing the proposal.",
+            file=sys.stderr,
+        )
+        return 2
     answers: dict[str, str] = {}
     if args.answers_file:
         try:

package/bundled-tools/clis/maggie_dash.py

@@ -102,8 +102,38 @@ def manifest_file_pairs(source: Path, manifest: dict[str, object], target: Path)
     return pairs
 
 
+def manifest_root_file_pairs(source: Path, manifest: dict[str, object], root: Path) -> list[tuple[Path, Path, Path]]:
+    """Return optional host-root files without changing the admin target contract."""
+    pairs: list[tuple[Path, Path, Path]] = []
+    for item in manifest.get("rootFiles", []):
+        if isinstance(item, str):
+            source_relative = Path(item)
+            target_relative = source_relative
+        elif isinstance(item, dict):
+            source_relative = Path(str(item.get("source", "")))
+            target_relative = Path(str(item.get("target", "")))
+        else:
+            raise RuntimeError("MaggieDash rootFiles entries must be strings or objects")
+        if not source_relative.parts or not target_relative.parts:
+            raise RuntimeError("MaggieDash rootFiles entries require source and target")
+        if source_relative.is_absolute() or target_relative.is_absolute() or ".." in source_relative.parts or ".." in target_relative.parts:
+            raise RuntimeError("unsafe MaggieDash rootFiles path")
+        source_item = source / source_relative
+        if source_item.is_file():
+            pairs.append((source_item, root / target_relative, source_relative))
+            continue
+        if not source_item.is_dir():
+            raise RuntimeError(f"MaggieDash rootFiles source is missing: {source_relative}")
+        for path in sorted(source_item.rglob("*")):
+            if path.is_file():
+                child = path.relative_to(source_item)
+                pairs.append((path, root / target_relative / child, source_relative / child))
+    return pairs
+
+
 def command_install_diff(source: Path, manifest: dict[str, object], target: Path, compare_dir: Path | None, force: bool) -> dict[str, object]:
     pairs = manifest_file_pairs(source, manifest, target)
+    root_pairs = manifest_root_file_pairs(source, manifest, target.parents[1])
     files: list[dict[str, str]] = []
     source_relative = {relative for _, _, relative in pairs}
     for source_file, destination, relative in pairs:
@@ -119,6 +149,15 @@ def command_install_diff(source: Path, manifest: dict[str, object], target: Path
         else:
             action = "update" if force else "preserve"
         files.append({"path": str(relative), "action": action, "comparePath": str(compare_file)})
+    for source_file, destination, relative in root_pairs:
+        compare_file = destination
+        if not compare_file.exists():
+            action = "add"
+        elif compare_file.read_bytes() == source_file.read_bytes():
+            action = "unchanged"
+        else:
+            action = "update" if force else "preserve"
+        files.append({"path": str(relative), "action": action, "comparePath": str(compare_file)})
     if compare_dir and compare_dir.exists():
         for existing in sorted(compare_dir.rglob("*")):
             if not existing.is_file():
@@ -204,6 +243,13 @@ def command_install(args: argparse.Namespace) -> int:
                     current_installed = [str(destination)]
             installed.extend(current_installed)
             preserved.extend(current_preserved)
+        for source_file, destination, _ in manifest_root_file_pairs(source, manifest, root):
+            if destination.exists() and not args.force:
+                preserved.append(str(destination))
+            else:
+                destination.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(source_file, destination)
+                installed.append(str(destination))
         state = {
             "schemaVersion": "maggiedash-install.v1",
             "status": "installed",
@@ -442,6 +488,62 @@ def command_api_contract(args: argparse.Namespace) -> int:
     return 0 if result["passed"] else 1
 
 
+def command_conformance(args: argparse.Namespace) -> int:
+    """Validate sanitized runtime evidence for every declared host endpoint."""
+    project = Path(getattr(args, "project", ".")).resolve()
+    def input_path(value: str) -> Path:
+        path = Path(value)
+        return path if path.is_absolute() else project / path
+    contract = json.loads(input_path(args.contract).read_text(encoding="utf-8"))
+    evidence = json.loads(input_path(args.evidence).read_text(encoding="utf-8"))
+    endpoints = contract.get("x-endpoints") or contract.get("endpoints") or contract.get("properties", {}).get("endpoints", {}).get("x-endpoints", [])
+    observations = evidence.get("observations") if isinstance(evidence, dict) else None
+    errors: list[str] = []
+    if not isinstance(endpoints, list) or not endpoints:
+        errors.append("contract must declare at least one endpoint")
+        endpoints = []
+    if not isinstance(observations, list):
+        errors.append("evidence.observations must be an array")
+        observations = []
+    by_id = {str(item.get("id")): item for item in observations if isinstance(item, dict) and item.get("id")}
+    checked = []
+    for endpoint in endpoints:
+        endpoint_id = str(endpoint.get("id", "")) if isinstance(endpoint, dict) else ""
+        item_errors: list[str] = []
+        observation = by_id.get(endpoint_id)
+        if not observation:
+            item_errors.append("missing runtime observation")
+        else:
+            if observation.get("method") != endpoint.get("method"):
+                item_errors.append("observed method does not match contract")
+            if observation.get("route") != endpoint.get("route"):
+                item_errors.append("observed route does not match contract")
+            status = observation.get("httpStatus")
+            if not isinstance(status, int) or isinstance(status, bool) or not 200 <= status < 300:
+                item_errors.append("endpoint did not return a 2xx status")
+            expected_type = endpoint.get("response", {}).get("contentType")
+            if observation.get("contentType") != expected_type:
+                item_errors.append("observed content type does not match contract")
+            fields = observation.get("responseFields")
+            required = endpoint.get("response", {}).get("requiredFields", [])
+            if not isinstance(fields, list) or not set(required).issubset(set(fields)):
+                item_errors.append("response is missing one or more declared fields")
+            if observation.get("passed") is not True:
+                item_errors.append("runtime observation is not passed")
+        checked.append({"id": endpoint_id, "passed": not item_errors, "errors": item_errors})
+    duplicate_ids = len(by_id) != len(observations)
+    if duplicate_ids:
+        errors.append("evidence contains duplicate or invalid observation ids")
+    report = {"schemaVersion": "maggiedash-host-conformance.v1", "checked": len(checked), "endpoints": checked, "errors": errors, "passed": not errors and bool(checked) and all(item["passed"] for item in checked)}
+    if args.output:
+        output = input_path(args.output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        report["output"] = str(output)
+    emit(report)
+    return 0 if report["passed"] else 1
+
+
 def command_schema_audit(args: argparse.Namespace) -> int:
     value = json.loads(Path(args.inventory).resolve().read_text(encoding="utf-8"))
     result = audit_schema_inventory(value, fail_on_unread=args.fail_on_unread)
@@ -603,6 +705,12 @@ def parser() -> argparse.ArgumentParser:
     api_contract = sub.add_parser("api-contract", help="validate a local or live declared request and success-response contract")
     api_contract.add_argument("--spec", required=True, help="local JSON file or HTTPS URL (loopback HTTP is allowed for development)")
     api_contract.set_defaults(func=command_api_contract)
+    conformance = sub.add_parser("conformance", help="validate one sanitized runtime observation for every declared MaggieDash endpoint")
+    conformance.add_argument("--project", default=".", help="host project root for relative contract, evidence, and output paths")
+    conformance.add_argument("--contract", required=True, help="MaggieDash host adapter contract JSON")
+    conformance.add_argument("--evidence", required=True, help="sanitized endpoint observations JSON")
+    conformance.add_argument("--output")
+    conformance.set_defaults(func=command_conformance)
     schema_audit = sub.add_parser("schema-audit", help="find declared tables with missing reader evidence")
     schema_audit.add_argument("--inventory", required=True, help="host-produced schema inventory JSON")
     schema_audit.add_argument("--fail-on-unread", action="store_true")

package/bundled-tools/clis/maggie_deployment.py

@@ -55,8 +55,7 @@ def preflight(project: Path, target: str, environment: str) -> dict:
         rollback_passed = False
         if rollback_evidence.exists():
             try:
-                evidence = json.loads(rollback_evidence.read_text(encoding="utf-8"))
-                rollback_passed = bool(evidence.get("passed") is True and evidence.get("environment") == "production" and evidence.get("previousRelease") and evidence.get("testedAt"))
+                rollback_passed = validate_rollback_evidence(json.loads(rollback_evidence.read_text(encoding="utf-8"))) ["passed"]
             except (OSError, json.JSONDecodeError):
                 rollback_passed = False
         migration_manifest = project / ".maggie" / "migration-manifest.json"
@@ -79,12 +78,14 @@ def preflight(project: Path, target: str, environment: str) -> dict:
     return result
 
 
-def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> dict:
+def vps_plan(domain: str, service: str, release_root: str, node_port: int | None) -> dict:
     """Create reviewable, secret-free VPS service and reverse-proxy artifacts."""
     if not re.fullmatch(r"[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?", domain):
         raise ValueError("domain must be a hostname without a scheme or path")
     if not re.fullmatch(r"[A-Za-z0-9_.@-]+", service):
         raise ValueError("service must contain only safe systemd name characters")
+    if node_port is None:
+        raise ValueError("node port must be supplied explicitly; choose an unused port for this host")
     if not 1024 <= node_port <= 65535:
         raise ValueError("node port must be between 1024 and 65535")
     root = release_root.rstrip("/")
@@ -97,6 +98,12 @@ def vps_plan(domain: str, service: str, release_root: str, node_port: int) -> di
         "release_root": root,
         "current_release": current,
         "node_port": node_port,
+        "proxy": {
+            "trust_forwarded_proto": True,
+            "forwarded_headers": ["X-Forwarded-Host", "X-Forwarded-Proto"],
+            "origin_check": "Astro security.checkOrigin remains enabled",
+            "allowed_domains_required": True,
+        },
         "release_layout": f"{root}/releases/<immutable-release> plus current symlink",
         "retention": {"keep": 2, "preserve": [current, f"{root}/releases/<previous-release>"], "prune": f"find {root}/releases -mindepth 1 -maxdepth 1 -type d -printf '%T@ %p\\n' | sort -nr | tail -n +3 | cut -d' ' -f2- | xargs -r rm -rf --"},
         "staging_first": True,
@@ -141,6 +148,32 @@ def validate_data_checkpoint(path: Path) -> dict:
     return {"passed": not errors, "declared": True, "errors": errors}
 
 
+def validate_rollback_evidence(value: object) -> dict:
+    """Validate release rollback evidence, including the explicitly safe first release."""
+    if not isinstance(value, dict):
+        return {"passed": False, "errors": ["rollback evidence must be an object"]}
+    errors = []
+    if value.get("schemaVersion") not in {None, "maggie-deployment-rollback.v1"}:
+        errors.append("rollback evidence schemaVersion is unsupported")
+    if value.get("passed") is not True:
+        errors.append("rollback evidence is not passed")
+    if value.get("environment") != "production":
+        errors.append("rollback evidence must target production")
+    if not value.get("testedAt"):
+        errors.append("rollback evidence testedAt is required")
+    release_kind = value.get("releaseKind", "upgrade")
+    if release_kind not in {"first", "upgrade"}:
+        errors.append("rollback evidence releaseKind must be first or upgrade")
+    if release_kind == "first":
+        if value.get("previousRelease"):
+            errors.append("first release evidence must not claim a previous release")
+        if not value.get("notApplicableReason"):
+            errors.append("first release evidence needs notApplicableReason")
+    elif not value.get("previousRelease"):
+        errors.append("upgrade rollback evidence requires previousRelease")
+    return {"passed": not errors, "errors": errors}
+
+
 def validate_scheduler_request(method: str, origin: str | None, has_auth: bool) -> dict:
     errors = []
     if method.upper() == "POST":
@@ -210,6 +243,7 @@ WantedBy=multi-user.target
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Host $host;
         proxy_set_header X-Forwarded-Proto $scheme;
     }}
 }}
@@ -230,10 +264,15 @@ set -euo pipefail
 
 # 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}}"
 RELEASE_ROOT="{root}"
 CURRENT="{current}"
 RELEASE="$RELEASE_ROOT/releases/$RELEASE_ID"
 PREVIOUS="$(readlink -f "$CURRENT" 2>/dev/null || true)"
+if [ "$RELEASE_KIND" != "first" ] && [ -z "$PREVIOUS" ]; then
+  echo "No previous release found; set RELEASE_KIND=first for the initial production release." >&2
+  exit 2
+fi
 mkdir -p "$RELEASE"
 cd "$RELEASE"
 
@@ -277,7 +316,7 @@ def main() -> int:
     parser.add_argument("--domain", help="canonical hostname for --vps-plan")
     parser.add_argument("--service", default="maggie-site", help="systemd service name")
     parser.add_argument("--release-root", default="/var/www/maggie-site", help="immutable release root")
-    parser.add_argument("--node-port", type=int, default=4321)
+    parser.add_argument("--node-port", type=int, required=False, default=None, help="unused host port; required with --vps-plan")
     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")

package/bundled-tools/clis/maggie_deployment_parity.py

@@ -14,6 +14,7 @@ from typing import Any
 SCHEMA = "maggie-deployment-runtime-parity.v1"
 ENVIRONMENTS = {"development", "staging", "production"}
 SAFE_ID = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$")
+SHA256 = re.compile(r"^[0-9a-f]{64}$")
 
 
 def load(path: Path) -> dict[str, Any]:
@@ -42,6 +43,38 @@ def validate(payload: dict[str, Any]) -> list[str]:
     if payload.get("passed") is not True:
         errors.append("parity evidence is not marked passed")
 
+    release = payload.get("release")
+    if not isinstance(release, dict):
+        errors.append("release evidence must be an object")
+        release = {}
+    for field in ("activeRevision", "expectedRevision", "rollbackRevision"):
+        if not isinstance(release.get(field), str) or not SAFE_ID.fullmatch(release[field]):
+            errors.append(f"release.{field} must be a safe identifier")
+    if release.get("activeRevision") != release.get("expectedRevision"):
+        errors.append("active release revision does not match expected revision")
+    if release.get("rollbackRevision") == release.get("activeRevision"):
+        errors.append("rollback revision must differ from the active revision")
+    if release.get("environment") != payload.get("environment"):
+        errors.append("release environment does not match parity environment")
+    for field in ("runtimeConfigHash", "expectedConfigHash"):
+        if not isinstance(release.get(field), str) or not SHA256.fullmatch(release[field]):
+            errors.append(f"release.{field} must be a SHA-256 hex digest")
+    if release.get("runtimeConfigHash") != release.get("expectedConfigHash"):
+        errors.append("active runtime configuration does not match expected configuration")
+    for field in ("migrationVersion", "expectedMigrationVersion", "workerRevision"):
+        if not isinstance(release.get(field), str) or not SAFE_ID.fullmatch(release[field]):
+            errors.append(f"release.{field} must be a safe identifier")
+    if release.get("migrationVersion") != release.get("expectedMigrationVersion"):
+        errors.append("active migration version does not match expected migration version")
+    assets = release.get("assetVersions")
+    if not isinstance(assets, list) or not assets:
+        errors.append("release.assetVersions must contain at least one asset hash")
+    for index, asset in enumerate(assets if isinstance(assets, list) else []):
+        if not isinstance(asset, dict) or not SAFE_ID.fullmatch(str(asset.get("name") or "")):
+            errors.append(f"release.assetVersions[{index}].name must be a safe identifier")
+        if not isinstance(asset, dict) or not SHA256.fullmatch(str(asset.get("sha256") or "")):
+            errors.append(f"release.assetVersions[{index}].sha256 must be a SHA-256 hex digest")
+
     worker = payload.get("worker")
     if not isinstance(worker, dict):
         errors.append("worker evidence must be an object")
@@ -58,6 +91,8 @@ def validate(payload: dict[str, Any]) -> list[str]:
         errors.append("worker.config has missing requirements")
     if config.get("passed") is not True:
         errors.append("worker.config did not pass")
+    if worker.get("revision") != release.get("activeRevision"):
+        errors.append("worker revision does not match the active release")
 
     migration = worker.get("migration")
     privilege = migration.get("privilegeCheck") if isinstance(migration, dict) else None
@@ -84,6 +119,8 @@ def validate(payload: dict[str, Any]) -> list[str]:
             errors.append(f"{prefix}.status must be a successful HTTP status")
         if route.get("passed") is not True:
             errors.append(f"{prefix} did not pass")
+        if route.get("releaseRevision") != release.get("activeRevision"):
+            errors.append(f"{prefix}.releaseRevision does not match the active release")
 
     processes = worker.get("residentProcesses")
     if not isinstance(processes, dict):
@@ -135,6 +172,11 @@ def parity(evidence: Path, output: Path) -> int:
         "status": "passed" if not errors else "failed",
         "passed": not errors,
         "checks": {
+            "activeRelease": "validated",
+            "runtimeConfiguration": "validated",
+            "migrationVersion": "validated",
+            "assetVersions": "validated",
+            "rollbackTarget": "validated",
             "workerConfig": "validated",
             "migrationPrivileges": "validated",
             "routeApis": "validated",

package/bundled-tools/clis/maggie_feedback.py

@@ -28,6 +28,10 @@ LOCAL_PATH_RE = re.compile(
 )
 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}$")
+MAX_ROUTE_IDS = 20
+MAX_VALIDATION_EVIDENCE = 20
 ACKNOWLEDGEMENT_KEYS = ("status", "feedbackId", "requestId")
 REPO_ROOT = Path(__file__).resolve().parents[2]
 
@@ -107,6 +111,29 @@ def load_json(path: Path) -> dict:
     return value
 
 
+def safe_route_ids(values: object) -> list[str]:
+    """Keep bounded route identifiers, never request bodies or local paths."""
+    if not isinstance(values, list):
+        return []
+    result = []
+    for value in values[:MAX_ROUTE_IDS]:
+        item = safe_text(value)
+        if SAFE_ROUTE_RE.fullmatch(item):
+            result.append(item)
+    return sorted(set(result))
+
+
+def safe_validation_evidence(values: object) -> list[str]:
+    if not isinstance(values, list):
+        return []
+    result = []
+    for value in values[:MAX_VALIDATION_EVIDENCE]:
+        item = safe_text(value)
+        if SAFE_EVIDENCE_RE.fullmatch(item):
+            result.append(item)
+    return sorted(set(result))
+
+
 def collect(args: argparse.Namespace) -> int:
     project = Path(args.project).resolve()
     report = load_json(Path(args.run_report)) if args.run_report else {}
@@ -132,6 +159,8 @@ def collect(args: argparse.Namespace) -> int:
     if priority not in {"low", "normal", "high", "critical"}:
         raise ValueError("priority must be low, normal, high, or critical")
     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", []))
     context = {"projectFingerprint": project_fingerprint(project)}
     if args.allow_project_context and args.context_note:
         context["note"] = safe_text(args.context_note)
@@ -156,6 +185,8 @@ def collect(args: argparse.Namespace) -> int:
         "validation": validation,
         "priority": priority,
         "affectedCli": affected_cli,
+        "routeIds": route_ids,
+        "validationEvidence": validation_evidence,
         "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)},
@@ -264,6 +295,8 @@ def collect_batch(args: argparse.Namespace) -> int:
         "phase": safe_text(manifest.get("phase")),
         "priority": safe_text(manifest.get("priority") or "normal"),
         "affected_cli": safe_text(manifest.get("affectedCli")),
+        "route_ids": safe_route_ids(manifest.get("routeIds", [])),
+        "validation_evidence": safe_validation_evidence(manifest.get("validationEvidence", [])),
     }
     paths = []
     for index, item in enumerate(items):
@@ -292,14 +325,82 @@ def collect_batch(args: argparse.Namespace) -> int:
             "batch_size": len(items),
             "priority": item.get("priority") or shared["priority"],
             "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"]),
         }
         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"])
         paths.append(collect(argparse.Namespace(**values)))
     print(json.dumps({"batchId": batch_id, "count": len(paths), "status": "drafts-created"}, ensure_ascii=False))
     return 0
 
 
+def batch_review(args: argparse.Namespace) -> int:
+    """Aggregate one bounded batch without exposing raw payloads or paths."""
+    project = Path(args.project).resolve()
+    batch_id = safe_text(args.batch_id)
+    if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
+        raise ValueError("batch ID is invalid")
+    records = []
+    expected_sizes = []
+    for path in sorted((project / ".maggie" / "feedback").glob("*.json")):
+        try:
+            data = read_feedback(path)
+        except (OSError, ValueError, json.JSONDecodeError):
+            continue
+        batch = data.get("batch") if isinstance(data.get("batch"), dict) else {}
+        if batch.get("batchId") != batch_id:
+            continue
+        if isinstance(batch.get("size"), int):
+            expected_sizes.append(batch["size"])
+        records.append({
+            "feedbackId": safe_text(data.get("feedbackId")),
+            "index": batch.get("index"),
+            "type": safe_text(data.get("type")),
+            "skill": safe_text(data.get("skill")),
+            "phase": safe_text(data.get("phase")),
+            "summary": safe_text(data.get("summary")),
+            "expected": safe_text(data.get("expected")),
+            "actual": safe_text(data.get("actual")),
+            "errorFingerprint": safe_text(data.get("errorFingerprint")),
+            "fixed": data.get("fixed") is True,
+            "resolution": safe_text(data.get("resolution")),
+            "validation": safe_text(data.get("validation")),
+            "routeIds": safe_route_ids(data.get("routeIds", [])),
+            "validationEvidence": safe_validation_evidence(data.get("validationEvidence", [])),
+        })
+    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))
+    seen_indexes = {item["index"] for item in records if isinstance(item["index"], int)}
+    duplicate_groups = {}
+    for item in records:
+        key = item["errorFingerprint"] or re.sub(r"\s+", " ", item["summary"].lower()).strip()
+        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]
+    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 = {
+        "schemaVersion": "maggie-feedback-batch-review.v1",
+        "batchId": batch_id,
+        "status": "passed" if records and not duplicates and len(records) == expected_count else "needs-review",
+        "expectedCount": expected_count,
+        "draftCount": len(records),
+        "missingIndexes": sorted(set(range(expected_count)) - seen_indexes),
+        "skills": sorted({item["skill"] for item in records if item["skill"]}),
+        "phases": sorted({item["phase"] for item in records if item["phase"]}),
+        "observations": records,
+        "duplicates": duplicates,
+        "privacy": {"rawPayloadsIncluded": False, "localPathsIncluded": False, "secretsRedacted": True},
+    }
+    output.parent.mkdir(parents=True, exist_ok=True)
+    output.write_text(json.dumps(report, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    print(json.dumps({"status": report["status"], "batchId": batch_id, "draftCount": len(records), "expectedCount": expected_count, "duplicates": len(duplicates), "report": str(output.resolve())}, ensure_ascii=False))
+    return 0 if report["status"] == "passed" else 1
+
+
 def main() -> int:
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument("--project", default=".")
@@ -329,9 +430,15 @@ def main() -> int:
     collect_parser.add_argument("--batch-size", type=int)
     collect_parser.add_argument("--priority", choices=("low", "normal", "high", "critical"), default="normal")
     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=[])
     batch_parser = sub.add_parser("batch")
     batch_parser.add_argument("--project", default=argparse.SUPPRESS)
     batch_parser.add_argument("--batch-file", required=True)
+    review_parser = sub.add_parser("batch-review")
+    review_parser.add_argument("--project", default=argparse.SUPPRESS)
+    review_parser.add_argument("--batch-id", required=True)
+    review_parser.add_argument("--output")
     preview_parser = sub.add_parser("preview")
     preview_parser.add_argument("feedback")
     preview_parser.add_argument("--format", choices=("json", "markdown"), default="json")
@@ -344,6 +451,7 @@ def main() -> int:
     try:
         if args.command == "collect": return collect(args)
         if args.command == "batch": return collect_batch(args)
+        if args.command == "batch-review": return batch_review(args)
         if args.command == "preview": return preview(args)
         if args.command == "submit": return submit(args)
         return list_feedback(args)

package/bundled-tools/clis/maggie_localization.py

@@ -216,7 +216,15 @@ def plan_job(args: argparse.Namespace) -> int:
         "translationGroupId": identity.get("translationGroupId", f"tg-{content_id}"),
         "sourceRevision": args.source_revision or (source_artifact or {}).get("sourceRevision") or content.get("sourceRevision", "unknown"),
         "status": "draft",
-        "translation": {"translationStatus": "draft", "isIndexable": False},
+        "translation": {
+            "translationStatus": "draft", "isIndexable": False,
+            "provenance": {
+                "operation": args.operation, "sourceRevision": args.source_revision or (source_artifact or {}).get("sourceRevision") or content.get("sourceRevision", "unknown"),
+                "sourceLanguage": args.source_lang, "targetLanguage": args.target_lang,
+                "targetLocale": args.locale, "market": args.market,
+                "evidenceIds": [f"content:{content_id}"], "createdAt": now(),
+            },
+        },
         "createdAt": now(),
     }
     if source_artifact:
@@ -246,6 +254,15 @@ def validate_job(path: Path, source_path: Path | None = None, render_path: Path
         errors.append("targetLocale must be a supported tag matching targetLanguage")
     translation = job.get("translation", {})
     generation = job.get("generationContract", {})
+    provenance = translation.get("provenance", {}) if isinstance(translation, dict) else {}
+    if not isinstance(provenance, dict):
+        errors.append("translation.provenance must be an object")
+        provenance = {}
+    for field in ("sourceLanguage", "targetLanguage", "targetLocale", "market"):
+        if provenance.get(field) != job.get({"sourceLanguage": "sourceLanguage", "targetLanguage": "targetLanguage", "targetLocale": "targetLocale", "market": "market"}[field]):
+            errors.append(f"translation.provenance.{field} does not match the job")
+    if provenance.get("sourceRevision") != job.get("sourceRevision"):
+        errors.append("translation.provenance.sourceRevision does not match the job")
     if generation.get("mode") and generation.get("mode") != job.get("operation"):
         errors.append("generationContract mode must match operation")
     if job.get("operation") == "rewrite" and not generation.get("allowStructuralRewrite"):