@topy-ai/maggie 0.7.50 → 0.7.52

package/bundled-tools/clis/maggie_bridge_host.py

@@ -0,0 +1,212 @@
+#!/usr/bin/env python3
+"""Readiness checks for a multi-tenant assistant bridge host (``maggie deployment bridge-*``).
+
+A bridge host runs many users' assistant sessions (a coding/assistant CLI
+plus MCP servers and skills) in one container on a VPS. The plan
+(``maggie-bridge-host.v1``) declares isolation, network, capacity, recycling,
+image retention and third-party account terms; three commands check it:
+
+- ``bridge-plan``: validates the declared plan;
+- ``bridge-collect-script``: prints a POSIX ``sh`` script that collects the
+  observed facts as JSON. Run it with ``ssh host 'sh -s' < collect.sh`` —
+  stdin avoids quoting JSON through ssh and zsh's lack of word splitting;
+- ``bridge-check``: compares the observed JSON with the plan.
+
+Lessons encoded here: tenant uids cannot reach their folders unless every
+parent is ``0711`` (traverse, no listing), tenant folders are ``0700``, the
+admin API listens on loopback only and is never proxied, idle sessions are
+evicted LRU at a cap, sessions recycle when MCP, skills or the CLI update,
+and images carry a label so only current + previous are kept, with a
+health-checked switch that rolls back.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import shlex
+import sys
+from datetime import date, datetime, timezone
+from pathlib import Path
+
+SCHEMA = "maggie-bridge-host.v1"
+SECRET_ENV = re.compile(r"TOKEN|SECRET|PASSWORD|API_KEY|PRIVATE|CREDENTIAL|_KEY$", re.I)
+LOOPBACK = re.compile(r"^(?:127\.0\.0\.1|\[::1\]|localhost):\d+$")
+TERMS_MAX_AGE_DAYS = 180
+
+
+def _mode(value: object) -> int | None:
+    text = str(value or "").strip()
+    return int(text, 8) if re.fullmatch(r"0?[0-7]{3}", text) else None
+
+
+def validate_plan(plan: dict, today: date | None = None) -> dict:
+    today = today or datetime.now(timezone.utc).date()
+    errors: list[str] = []
+    warnings: list[str] = []
+    if plan.get("schemaVersion") != SCHEMA:
+        errors.append(f"schemaVersion must be {SCHEMA}")
+    if not str(plan.get("tenantsRoot", "")).startswith("/"):
+        errors.append("tenantsRoot must be an absolute path")
+    iso = plan.get("isolation", {}) if isinstance(plan.get("isolation"), dict) else {}
+    if iso.get("uidPerTenant") is not True:
+        errors.append("isolation.uidPerTenant must be true: one OS uid per tenant")
+    uid_range = iso.get("uidRange")
+    if not (isinstance(uid_range, list) and len(uid_range) == 2 and all(isinstance(v, int) for v in uid_range) and 10000 <= uid_range[0] < uid_range[1]):
+        errors.append("isolation.uidRange must be [first, last] at or above 10000 (clear of system and login users)")
+    if _mode(iso.get("tenantDirMode")) != 0o700:
+        errors.append("isolation.tenantDirMode must be 0700")
+    parent = _mode(iso.get("parentDirMode"))
+    if parent != 0o711:
+        errors.append("isolation.parentDirMode must be 0711: tenants traverse the parents without listing other tenants" + (" (0700 locks tenants out of their own folders)" if parent == 0o700 else ""))
+    if iso.get("cleanEnvironment") is not True:
+        errors.append("isolation.cleanEnvironment must be true: start each session with an allowlisted environment")
+    leaked = [name for name in iso.get("envAllowlist", []) or [] if SECRET_ENV.search(str(name))]
+    if leaked:
+        errors.append("isolation.envAllowlist passes secret-looking variables to tenant sessions: " + ", ".join(leaked))
+    if iso.get("ownerPinning") is not True:
+        errors.append("isolation.ownerPinning must be true: a session runs only for the tenant that owns it")
+    if iso.get("nonDumpable") is not True:
+        warnings.append("isolation.nonDumpable is not set; mark sessions non-dumpable after dropping to the tenant uid")
+    net = plan.get("network", {}) if isinstance(plan.get("network"), dict) else {}
+    if not LOOPBACK.match(str(net.get("adminBind", ""))):
+        errors.append("network.adminBind must be a loopback address:port")
+    if net.get("adminProxied") is not False:
+        errors.append("network.adminProxied must be false: the admin API is never exposed through the reverse proxy")
+    if net.get("proxy") and not LOOPBACK.match(str(net.get("publicBind", ""))):
+        errors.append("network.publicBind must be loopback when a reverse proxy fronts the host")
+    if net.get("adminBind") and net.get("adminBind") == net.get("publicBind"):
+        errors.append("admin and public APIs must listen on different ports")
+    cap = plan.get("capacity", {}) if isinstance(plan.get("capacity"), dict) else {}
+    if not isinstance(cap.get("maxSessions"), int) or cap["maxSessions"] < 1:
+        errors.append("capacity.maxSessions must be a positive integer")
+    if cap.get("eviction") not in {"lru-idle"}:
+        errors.append("capacity.eviction must be lru-idle: at the cap, stop the least recently used idle session")
+    if not isinstance(cap.get("idleTimeoutMinutes"), int) or not 1 <= cap["idleTimeoutMinutes"] <= 240:
+        warnings.append("capacity.idleTimeoutMinutes should stop idle sessions within 1-240 minutes")
+    recycle = plan.get("recycle", {}) if isinstance(plan.get("recycle"), dict) else {}
+    missing = sorted({"mcp", "skills", "cli"} - set(recycle.get("on", []) or []))
+    if missing:
+        errors.append("recycle.on must include " + ", ".join(missing) + ": sessions keep stale tools until recycled")
+    if recycle.get("busySessions") != "after-current-turn":
+        warnings.append("recycle.busySessions should be after-current-turn so an update never cuts a reply")
+    image = plan.get("image", {}) if isinstance(plan.get("image"), dict) else {}
+    if not re.fullmatch(r"[a-z0-9.-]+=[A-Za-z0-9._-]+", str(image.get("label", ""))):
+        errors.append("image.label must be key=value so cleanup can find this host's images")
+    if not isinstance(image.get("retain"), int) or image["retain"] < 2:
+        errors.append("image.retain must be at least 2 (current + previous for rollback)")
+    health = image.get("healthcheck", {}) if isinstance(image.get("healthcheck"), dict) else {}
+    if not str(health.get("path", "")).startswith("/") or not isinstance(health.get("attempts"), int):
+        errors.append("image.healthcheck needs a path and attempts")
+    if image.get("rollback") is not True:
+        errors.append("image.rollback must be true: a failed health check restores the previous container")
+    for key in ("readOnlyRootfs", "capDropAll", "noNewPrivileges"):
+        if image.get(key) is not True:
+            warnings.append(f"image.{key} is not set")
+    providers = plan.get("providers")
+    if not isinstance(providers, list) or not providers:
+        errors.append("providers must list each third-party AI account type the host runs, with a terms review")
+    for provider in providers if isinstance(providers, list) else []:
+        name = provider.get("name", "?")
+        reviewed = provider.get("termsReviewedAt")
+        if not reviewed or not provider.get("termsUrl"):
+            errors.append(f"provider {name}: record termsUrl and termsReviewedAt")
+        else:
+            age = (today - date.fromisoformat(str(reviewed)[:10])).days
+            if age > TERMS_MAX_AGE_DAYS:
+                warnings.append(f"provider {name}: terms reviewed {age} days ago; review again")
+        if provider.get("accountType") == "shared" and provider.get("allowsHostedMultiUser") is not True:
+            errors.append(f"provider {name}: a shared account may only serve several users when the terms allow hosted multi-user use")
+        if provider.get("accountType") not in {"customer-own", "shared"}:
+            errors.append(f"provider {name}: accountType must be customer-own or shared")
+    return {"schemaVersion": "maggie-bridge-host-plan-check.v1", "passed": not errors, "errors": errors, "warnings": warnings}
+
+
+def collect_script(plan: dict) -> str:
+    """A POSIX sh collector; values are quoted once here and the script is sent over ssh stdin."""
+    root = shlex.quote(str(plan.get("tenantsRoot", "/var/lib/bridge/tenants")))
+    label = shlex.quote(str(plan.get("image", {}).get("label", "")))
+    ports = " ".join(shlex.quote(str(plan.get("network", {}).get(key, "")).rsplit(":", 1)[-1]) for key in ("publicBind", "adminBind"))
+    return f"""#!/bin/sh
+# maggie bridge-host collector: prints JSON facts only (modes, uids, listeners, image count).
+# Run: ssh <host> 'sh -s' < collect.sh > observed.json
+set -eu
+root={root}
+printf '{{"schemaVersion":"maggie-bridge-host-observed.v1","parents":['
+sep=''
+dir="$root"
+while [ "$dir" != "/" ]; do
+  printf '%s{{"path":"%s","mode":"%s"}}' "$sep" "$dir" "$(stat -c %a "$dir")"; sep=','
+  dir=$(dirname "$dir")
+done
+printf '],"tenants":['
+sep=''
+for t in "$root"/*; do
+  [ -d "$t" ] || continue
+  printf '%s{{"name":"%s","mode":"%s","uid":%s}}' "$sep" "$(basename "$t")" "$(stat -c %a "$t")" "$(stat -c %u "$t")"; sep=','
+done
+printf '],"listeners":['
+listeners=$(for port in {ports}; do ss -ltnH "sport = :$port" 2>/dev/null | awk '{{print $4}}'; done)
+sep=''
+for local in $listeners; do printf '%s"%s"' "$sep" "$local"; sep=','; done
+printf '],"images":%s}}\\n' "$(docker images --filter label={label} --format '{{{{.ID}}}}' 2>/dev/null | sort -u | wc -l)"
+"""
+
+
+def check_observed(plan: dict, observed: dict) -> dict:
+    errors: list[str] = []
+    iso = plan.get("isolation", {})
+    first, last = (iso.get("uidRange") or [10000, 10**9])[:2]
+    parents = observed.get("parents", [])
+    for item in parents[1:]:  # ancestors only need traverse (x) for other users
+        mode = _mode(item.get("mode"))
+        if mode is None or not mode & 0o001:
+            errors.append(f"parent {item.get('path')} is {item.get('mode')}: tenant uids cannot traverse it (others need x, e.g. 0711)")
+    if parents and _mode(parents[0].get("mode")) != _mode(iso.get("parentDirMode", "0711")):
+        errors.append(f"tenants root {parents[0].get('path')} is {parents[0].get('mode')}, plan says {iso.get('parentDirMode')}")
+    uids: dict[int, str] = {}
+    for tenant in observed.get("tenants", []):
+        name, uid = tenant.get("name"), tenant.get("uid")
+        if _mode(tenant.get("mode")) != 0o700:
+            errors.append(f"tenant {name} is {tenant.get('mode')}, not 0700")
+        if not isinstance(uid, int) or not first <= uid <= last:
+            errors.append(f"tenant {name} uid {uid} is outside {first}-{last}")
+        elif uid in uids:
+            errors.append(f"tenants {uids[uid]} and {name} share uid {uid}")
+        else:
+            uids[uid] = name
+    admin_port = str(plan.get("network", {}).get("adminBind", "")).rsplit(":", 1)[-1]
+    for listener in observed.get("listeners", []):
+        host, _, port = str(listener).rpartition(":")
+        if port == admin_port and host not in {"127.0.0.1", "[::1]", "::1"}:
+            errors.append(f"admin port {port} listens on {host or '*'}, not loopback")
+    retain = plan.get("image", {}).get("retain", 2)
+    if isinstance(observed.get("images"), int) and observed["images"] > retain:
+        errors.append(f"{observed['images']} labelled images on the host; keep {retain} (current + previous)")
+    return {"schemaVersion": "maggie-bridge-host-check.v1", "passed": not errors, "tenants": len(observed.get("tenants", [])), "errors": errors}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="maggie deployment bridge", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = parser.add_subparsers(dest="command", required=True)
+    for name in ("bridge-plan", "bridge-collect-script", "bridge-check"):
+        command = sub.add_parser(name)
+        command.add_argument("--plan", type=Path, required=True)
+        if name == "bridge-check":
+            command.add_argument("--observed", type=Path, required=True)
+    args = parser.parse_args(argv)
+    try:
+        plan = json.loads(args.plan.read_text(encoding="utf-8"))
+        if args.command == "bridge-collect-script":
+            print(collect_script(plan), end=""); return 0
+        report = validate_plan(plan) if args.command == "bridge-plan" else check_observed(plan, json.loads(args.observed.read_text(encoding="utf-8")))
+    except (OSError, ValueError, json.JSONDecodeError) as error:
+        print(f"BLOCKED: maggie deployment {args.command}: {error}", file=sys.stderr)
+        return 2
+    print(json.dumps(report, indent=2, ensure_ascii=False))
+    return 0 if report["passed"] else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundled-tools/clis/maggie_design.py

@@ -202,13 +202,83 @@ def validate_content_ui(project: Path, plan_path: Path, rendered_dir: Path | Non
     output = plan_path.parent / "validation.json"; output.write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"); print(json.dumps(result, indent=2, ensure_ascii=False)); return 0 if not errors else 1
 
 
-def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, confirm: bool) -> int:
+APP_CAPABILITY_STATES = {
+    "camera": ["permission", "ready", "gallery", "scan", "unavailable"],
+    "location": ["permission", "granted", "denied", "unavailable"],
+    "notifications": ["permission", "granted", "denied"],
+    "media-library": ["permission", "granted", "denied", "empty"],
+}
+APP_PATTERNS = ("tabbed-modal", "editor-sheet-assistant", "usage-hero", "site-switcher")
+
+
+def parse_app_capabilities(value: str | None) -> list[str]:
+    """Parse ``--capabilities`` (``none`` or a comma list); ``None`` keeps the camera default."""
+    if value is None:
+        return ["camera"]
+    names = [item.strip() for item in value.split(",") if item.strip()]
+    if names == ["none"] or not names:
+        return []
+    unknown = sorted(set(names) - set(APP_CAPABILITY_STATES))
+    if unknown or "none" in names:
+        raise ValueError(f"unsupported app capability: {', '.join(unknown) or 'none mixed with others'} (use none or {', '.join(APP_CAPABILITY_STATES)})")
+    return sorted(set(names), key=names.index)
+
+
+def parse_app_panes(values: list[str] | None) -> list[dict]:
+    """Parse ``--pane NAME:MIN_WIDTH:SCROLL_OWNERS`` declarations of intentional multi-pane layouts."""
+    panes = []
+    for value in values or []:
+        match = re.fullmatch(r"([a-z0-9][a-z0-9-]*):(\d{3,4}):([2-4])", value.strip())
+        if not match:
+            raise ValueError(f"--pane must look like list-detail:1024:2 (name, min width px, 2-4 scroll owners): {value}")
+        panes.append({"name": match.group(1), "minWidth": int(match.group(2)), "scrollOwners": int(match.group(3))})
+    return panes
+
+
+def parse_app_viewports(values: list[str] | None) -> dict[str, list[int]]:
+    viewports = {name: list(size) for name, size in REVIEW_VIEWPORTS.items()}
+    for value in values or []:
+        match = re.fullmatch(r"(desktop|tablet|mobile)=(\d{3,4})x(\d{3,4})", value.strip())
+        if not match:
+            raise ValueError(f"--viewport must look like tablet=768x1024: {value}")
+        viewports[match.group(1)] = [int(match.group(2)), int(match.group(3))]
+    return viewports
+
+
+def expected_scroll_owners(plan: dict, width: int) -> int:
+    """Return the scroll owners a viewport may have: one, unless a declared pane layout applies."""
+    owners = plan.get("shell", {}).get("scrollOwners", {}) if isinstance(plan.get("shell"), dict) else {}
+    expected = int(owners.get("default", 1)) if isinstance(owners, dict) else 1
+    for pane in (owners.get("intentionalPanes", []) if isinstance(owners, dict) else []):
+        if isinstance(pane, dict) and isinstance(pane.get("minWidth"), int) and width >= pane["minWidth"]:
+            expected = max(expected, int(pane.get("scrollOwners", 1)))
+    return expected
+
+
+def png_size(path: Path) -> tuple[int, int] | None:
+    """Return a PNG's IHDR width and height, or ``None`` when the file is not a PNG."""
+    try:
+        head = path.read_bytes()[:24]
+    except OSError:
+        return None
+    if len(head) < 24 or head[:8] != b"\x89PNG\r\n\x1a\n" or head[12:16] != b"IHDR":
+        return None
+    return int.from_bytes(head[16:20], "big"), int.from_bytes(head[20:24], "big")
+
+
+def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, confirm: bool, capabilities: list[str] | None = None, panes: list[dict] | None = None, viewports: dict[str, list[int]] | None = None, patterns: list[str] | None = None) -> int:
     """Create a host-owned mobile app surface contract and QA manifest."""
     project = project.resolve()
     if not route.startswith("/") or "?" in route or "#" in route:
         raise ValueError("route must be a path beginning with / and must not contain a query or hash")
     if auth_mode not in {"email-password", "existing-session", "none"}:
         raise ValueError("auth mode must be email-password, existing-session, or none")
+    capabilities = ["camera"] if capabilities is None else capabilities
+    panes = panes or []
+    patterns = patterns or []
+    unknown_patterns = sorted(set(patterns) - set(APP_PATTERNS))
+    if unknown_patterns:
+        raise ValueError(f"unsupported app pattern: {', '.join(unknown_patterns)} (use {', '.join(APP_PATTERNS)})")
     contract = require_design_contract(project)
     relative = route.strip("/")
     candidates = [
@@ -218,6 +288,11 @@ def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, con
         project / "src" / "pages" / f"{relative}.html",
         project / "src" / "app" / relative,
         project / "src" / "app" / relative / "page.tsx",
+        # Expo Router file routes (app/ or src/app/, with optional (group) folders resolved by the host).
+        project / "app" / f"{relative}.tsx",
+        project / "app" / relative / "index.tsx",
+        project / "src" / "app" / f"{relative}.tsx",
+        project / "src" / "app" / relative / "index.tsx",
     ]
     source = next((path for path in candidates if path.is_file()), None)
     digest = hashlib.sha256((str(project) + "\n" + route + "\n" + auth_mode).encode()).hexdigest()[:12]
@@ -226,7 +301,15 @@ def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, con
         print((output_dir / "plan.json").read_text(encoding="utf-8"), end="")
         return 0
     output_dir.mkdir(parents=True, exist_ok=True)
-    viewports = {"desktop": REVIEW_VIEWPORTS["desktop"], "tablet": REVIEW_VIEWPORTS["tablet"], "mobile": REVIEW_VIEWPORTS["mobile"]}
+    viewports = viewports or {name: list(size) for name, size in REVIEW_VIEWPORTS.items()}
+    camera = "camera" in capabilities
+    capability_contract = {name: {"requiredStates": list(APP_CAPABILITY_STATES[name])} for name in capabilities}
+    required_steps = ["inspect-host-shell", "define-auth-gate"]
+    if capabilities:
+        required_steps.append("define-capability-states")
+    if camera:
+        required_steps.append("define-camera-states")
+    required_steps += ["capture-desktop-tablet-mobile", "signed-in-browser-qa", "accessibility-check", "route-validation", "explicit-approval"]
     plan = {
         "schemaVersion": "maggie-mobile-app-surface.v1",
         "id": f"app-{digest}",
@@ -237,11 +320,17 @@ def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, con
         "routeSource": str(source) if source else None,
         "designContract": contract,
         "auth": {"mode": auth_mode, "required": auth_mode != "none", "credentialPolicy": "use-host-auth-without-recording-credentials"},
-        "shell": {"fixedHeader": True, "fixedFooter": True, "oneScrollOwner": True, "cameraMayUseFullScreenViewport": True, "hostShellSourceOfTruth": "existing homepage shell"},
-        "camera": {"requiredStates": ["permission", "ready", "gallery", "scan", "unavailable"], "controls": ["close", "gallery", "shutter", "mode"], "fallback": "show an actionable unavailable state; never leave a black screen"},
-        "decisionCriticalUi": ["card normalization", "graded-price fallback", "grade-9-to-10 economics", "scan-to-inventory or valuation transition"],
+        "shell": {
+            "fixedHeader": True, "fixedFooter": True, "oneScrollOwner": not panes,
+            "scrollOwners": {"default": 1, "intentionalPanes": panes, "rule": "per-viewport evidence must match; more than one owner only where a declared pane layout applies"},
+            "cameraMayUseFullScreenViewport": camera, "hostShellSourceOfTruth": "existing homepage shell",
+        },
+        "capabilities": capability_contract,
+        "camera": {"requiredStates": list(APP_CAPABILITY_STATES["camera"]), "controls": ["close", "gallery", "shutter", "mode"], "fallback": "show an actionable unavailable state; never leave a black screen"} if camera else {"requiredStates": [], "notApplicable": "route declares no camera capability"},
+        "patterns": patterns,
+        "decisionCriticalUi": [],
         "viewports": viewports,
-        "requiredSteps": ["inspect-host-shell", "define-auth-gate", "define-camera-states", "capture-desktop-tablet-mobile", "signed-in-browser-qa", "accessibility-check", "route-validation", "explicit-approval"],
+        "requiredSteps": required_steps,
         "provenance": {"hostOwnsAuthAndCamera": True, "designContractReused": True, "privateDataCopied": False},
         "publicWrite": False,
         "createdAt": datetime.now(timezone.utc).isoformat(),
@@ -250,36 +339,58 @@ def app_surface_init(project: Path, route: str, auth_mode: str, force: bool, con
         "schemaVersion": "maggie-mobile-app-evidence.v1",
         "route": route,
         "auth": plan["auth"],
-        "shell": plan["shell"],
-        "camera": plan["camera"],
-        "viewports": {name: {"screenshot": f"{name}.png", "captured": False} for name in viewports},
+        "shell": {key: plan["shell"][key] for key in ("fixedHeader", "fixedFooter")},
+        "capabilities": {name: {"states": []} for name in capabilities},
+        "viewports": {name: {"width": size[0], "height": size[1], "deviceScaleFactor": 1, "scrollOwners": None, "screenshot": f"{name}.png", "captured": False} for name, size in viewports.items()},
         "status": "pending",
+        "collectWith": "maggie design app-collect",
     }
-    qa = {"schemaVersion": "maggie-mobile-app-qa.v1", "route": route, "auth": plan["auth"], "scenarios": [
-        {"id": "shell-scroll", "viewport": "mobile", "assertions": ["fixed header and footer remain usable", "exactly one scroll owner"]},
-        {"id": "camera-permission", "viewport": "mobile", "assertions": ["permission state is explained", "denied permission shows fallback"]},
-        {"id": "camera-scan", "viewport": "mobile", "assertions": ["gallery/shutter/mode/close controls are reachable", "scan result can enter inventory or valuation"]},
-        {"id": "valuation-auth", "viewport": "desktop", "assertions": ["signed-in route does not redirect unexpectedly", "grade economics and fallback price remain legible"]},
-    ]}
+    scenarios = [{"id": "shell-scroll", "viewport": "mobile", "assertions": ["fixed header and footer remain usable", "exactly one scroll owner"]}]
+    for pane in panes:
+        scenarios.append({"id": f"panes-{pane['name']}", "viewport": "desktop", "assertions": [f"from {pane['minWidth']} px the {pane['name']} layout has {pane['scrollOwners']} independent scroll owners", f"below {pane['minWidth']} px the layout collapses to one scroll owner"]})
+    if camera:
+        scenarios += [
+            {"id": "camera-permission", "viewport": "mobile", "assertions": ["permission state is explained", "denied permission shows fallback"]},
+            {"id": "camera-capture", "viewport": "mobile", "assertions": ["gallery/shutter/mode/close controls are reachable", "a capture result reaches the next step of the flow"]},
+        ]
+    for name in capabilities:
+        if name != "camera":
+            scenarios.append({"id": f"{name}-permission", "viewport": "mobile", "assertions": [f"{name} permission is explained before the system prompt", "denied permission leaves an actionable fallback"]})
+    scenarios.append({"id": "ios-safe-area", "viewport": "notched iPhone (device or simulator)", "assertions": ["header and Close sit below the status bar / Dynamic Island in every modal and sheet", "insets come from useSafeAreaInsets(), not SafeAreaView inside a modal (`maggie design safe-area-check`)", "web screenshots cannot prove this; record a device screenshot"]})
+    for pattern in patterns:
+        scenarios.append({"id": f"pattern-{pattern}", "viewport": "all", "assertions": APP_PATTERN_ACCEPTANCE[pattern]})
+    if auth_mode != "none":
+        scenarios.append({"id": "signed-in-route", "viewport": "desktop", "assertions": ["signed-in route does not redirect unexpectedly", "render one app instance at a time when refresh tokens rotate"]})
+    qa = {"schemaVersion": "maggie-mobile-app-qa.v1", "route": route, "auth": plan["auth"], "scenarios": scenarios}
     (output_dir / "plan.json").write_text(json.dumps(plan, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     (output_dir / "qa-scenarios.json").write_text(json.dumps(qa, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     (output_dir / "validation.json").write_text(json.dumps(evidence, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     (output_dir / "screenshots").mkdir(exist_ok=True)
-    print(json.dumps({"plan": str(output_dir / "plan.json"), "qaScenarios": str(output_dir / "qa-scenarios.json"), "surface": "app", "phase": "ready", "publicWrite": False}, indent=2, ensure_ascii=False))
+    print(json.dumps({"plan": str(output_dir / "plan.json"), "qaScenarios": str(output_dir / "qa-scenarios.json"), "surface": "app", "capabilities": capabilities, "panes": panes, "patterns": patterns, "phase": "ready", "publicWrite": False}, indent=2, ensure_ascii=False))
     return 0
 
 
+APP_PATTERN_ACCEPTANCE = {
+    "tabbed-modal": ["full screen below 768 px, centred card from 768 px", "the active pill tab scrolls into view", "switching tabs resets the tab body scroll", "close and Escape return focus to the opener"],
+    "editor-sheet-assistant": ["'Ask the assistant' turns the same sheet into a short contextual chat", "writes appear as an approval card; nothing changes until approved", "dismissing the chat restores the unsaved edit"],
+    "usage-hero": ["plan name, used and remaining quota are visible without scrolling", "the over-limit state names the next action"],
+    "site-switcher": ["favicon falls back to the site initial", "search appears from 5 sites", "the current site is marked and keyboard reachable"],
+}
+
+
 def validate_app_surface(project: Path, plan_path: Path, rendered_dir: Path | None, runtime_evidence: Path | None, confirm: bool) -> int:
-    """Validate signed-in app evidence and responsive screenshots."""
+    """Validate signed-in app evidence and responsive screenshots against the plan."""
     project = project.resolve(); plan_path = plan_path.resolve()
     if not plan_path.exists(): raise ValueError(f"app surface plan not found: {plan_path}")
-    plan = json.loads(plan_path.read_text(encoding="utf-8")); errors = []
+    plan = json.loads(plan_path.read_text(encoding="utf-8")); errors = []; warnings = []
     if plan.get("workflow") != "maggie-design" or plan.get("mode") != "app-view-init": errors.append("invalid mobile app surface plan")
     if plan.get("publicWrite") is not False: errors.append("publicWrite must remain false before approval")
-    if not plan.get("shell", {}).get("oneScrollOwner"): errors.append("app surface must define one scroll owner")
+    shell_plan = plan.get("shell", {})
+    if not shell_plan.get("oneScrollOwner") and not isinstance(shell_plan.get("scrollOwners"), dict): errors.append("app surface must define its scroll owners")
     if not plan.get("auth", {}).get("credentialPolicy"): errors.append("app surface must define a credential policy")
     try: require_design_contract(project)
     except ValueError as error: errors.append(str(error))
+    plan_viewports = {name: list(plan.get("viewports", {}).get(name) or REVIEW_VIEWPORTS[name]) for name in ("desktop", "tablet", "mobile")}
     evidence = {}
     evidence_path = runtime_evidence.resolve() if runtime_evidence else plan_path.parent / "runtime-evidence.json"
     if evidence_path.is_file():
@@ -287,23 +398,60 @@ def validate_app_surface(project: Path, plan_path: Path, rendered_dir: Path | No
         except json.JSONDecodeError: errors.append("runtime evidence is not valid JSON")
     else:
         errors.append("runtime evidence file is required")
+    evidence_viewports = evidence.get("viewports", {}) if isinstance(evidence.get("viewports"), dict) else {}
+    viewport_checks = {}
     if evidence:
         if evidence.get("schemaVersion") != "maggie-mobile-app-evidence.v1": errors.append("runtime evidence schemaVersion is invalid")
         if evidence.get("route") != plan.get("route"): errors.append("runtime evidence route does not match plan")
         auth = evidence.get("auth", {})
         if plan.get("auth", {}).get("required") and auth.get("signedIn") is not True: errors.append("signed-in evidence is required for this app route")
         shell = evidence.get("shell", {})
-        if shell.get("fixedHeader") is not True or shell.get("fixedFooter") is not True or shell.get("scrollOwnerCount") != 1: errors.append("runtime evidence must prove fixed shell and one scroll owner")
-        camera = evidence.get("camera", {})
-        camera_states = set(camera.get("states", [])) if isinstance(camera, dict) else set()
-        if not set(plan.get("camera", {}).get("requiredStates", [])).issubset(camera_states): errors.append("runtime evidence is missing a required camera state")
+        if "scrollOwnerCount" in shell:
+            warnings.append("shell.scrollOwnerCount is ignored; per-viewport scrollOwners are authoritative")
+        for name, (width, height) in plan_viewports.items():
+            entry = evidence_viewports.get(name)
+            check = {"planViewport": [width, height], "expectedScrollOwners": expected_scroll_owners(plan, width)}
+            viewport_checks[name] = check
+            if not isinstance(entry, dict):
+                errors.append(f"runtime evidence has no {name} viewport entry; collect it with `maggie design app-collect`"); continue
+            if [entry.get("width"), entry.get("height")] != [width, height]:
+                errors.append(f"{name} evidence viewport {entry.get('width')}x{entry.get('height')} does not match plan viewport {width}x{height}")
+            owners = entry.get("scrollOwners")
+            check["scrollOwners"] = owners
+            if not isinstance(owners, int):
+                errors.append(f"{name} evidence must record scrollOwners")
+            elif owners != check["expectedScrollOwners"]:
+                errors.append(f"{name} has {owners} scroll owners; the plan allows {check['expectedScrollOwners']} at {width} px")
+            for key in ("fixedHeader", "fixedFooter"):
+                value = entry.get(key, shell.get(key))
+                if value is not True:
+                    errors.append(f"runtime evidence must prove fixed shell ({key}) at {name}")
+        capability_states = evidence.get("capabilities", {}) if isinstance(evidence.get("capabilities"), dict) else {}
+        required = plan.get("capabilities")
+        if not isinstance(required, dict):  # plans created before capability flags
+            required = {"camera": {"requiredStates": plan.get("camera", {}).get("requiredStates", [])}}
+        for name, spec in required.items():
+            states = capability_states.get(name, {}).get("states", []) if isinstance(capability_states.get(name), dict) else []
+            if name == "camera" and not states and isinstance(evidence.get("camera"), dict):
+                states = evidence["camera"].get("states", [])
+            missing = sorted(set(spec.get("requiredStates", [])) - set(states))
+            if missing:
+                errors.append(f"runtime evidence is missing a required {name} state: {', '.join(missing)}" if name != "camera" else f"runtime evidence is missing a required camera state: {', '.join(missing)}")
     screenshot_status = {}
-    for name in ("desktop", "tablet", "mobile"):
+    for name, (width, height) in plan_viewports.items():
         path = (rendered_dir / f"{name}.png") if rendered_dir else plan_path.parent / "screenshots" / f"{name}.png"
-        valid = path.is_file() and path.read_bytes()[:8] == b"\x89PNG\r\n\x1a\n"
-        screenshot_status[name] = {"path": str(path), "validPng": valid}
-        if not valid: errors.append(f"missing valid {name} screenshot")
-    result = {"schemaVersion": "maggie-mobile-app-validation.v1", "plan": str(plan_path), "route": plan.get("route"), "screenshots": screenshot_status, "runtimeEvidence": str(evidence_path), "checks": {"fixedShell": not any("fixed shell" in error for error in errors), "signedInRoute": not any("signed-in" in error for error in errors), "cameraStates": not any("camera state" in error for error in errors), "publicWriteBlocked": plan.get("publicWrite") is False}, "status": "passed" if not errors else "failed", "errors": errors, "validatedAt": datetime.now(timezone.utc).isoformat()}
+        size = png_size(path) if path.is_file() else None
+        entry = evidence_viewports.get(name) if isinstance(evidence_viewports.get(name), dict) else {}
+        scale = entry.get("deviceScaleFactor", 1) or 1
+        full_page = entry.get("fullPage") is True
+        screenshot_status[name] = {"path": str(path), "validPng": size is not None, "size": list(size) if size else None, "deviceScaleFactor": scale}
+        if size is None:
+            errors.append(f"missing valid {name} screenshot"); continue
+        expected_w, expected_h = round(width * scale), round(height * scale)
+        if size[0] != expected_w or (size[1] < expected_h if full_page else size[1] != expected_h):
+            errors.append(f"{name} screenshot is {size[0]}x{size[1]} but the plan viewport is {width}x{height} at scale {scale} (expected {expected_w}x{expected_h}{' or taller' if full_page else ''}); capture at the real viewport, not a scaled frame")
+    result = {"schemaVersion": "maggie-mobile-app-validation.v1", "plan": str(plan_path), "route": plan.get("route"), "screenshots": screenshot_status, "viewports": viewport_checks, "runtimeEvidence": str(evidence_path), "checks": {"fixedShell": not any("fixed shell" in error for error in errors), "scrollOwners": not any("scroll owner" in error for error in errors), "viewportsMatchPlan": not any("does not match plan viewport" in error or "screenshot is" in error for error in errors), "signedInRoute": not any("signed-in" in error for error in errors), "capabilityStates": not any(" state" in error and "required" in error for error in errors), "publicWriteBlocked": plan.get("publicWrite") is False}, "status": "passed" if not errors else "failed", "errors": errors, "warnings": warnings, "validatedAt": datetime.now(timezone.utc).isoformat()}
+    result["checks"]["cameraStates"] = not any("camera state" in error for error in errors)
     if confirm:
         plan_path.parent.joinpath("validation.json").write_text(json.dumps(result, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
     print(json.dumps(result, indent=2, ensure_ascii=False))
@@ -856,18 +1004,23 @@ commands:
   markup-check validate optional style attributes, content keys, and entities
   pressable-check flag pressables/buttons nested in another pressable (JSX/TSX)
   layer-check  flag unlayered CSS that overrides Tailwind v4 utilities
+  safe-area-check flag SafeAreaView inside iOS modal routes / RN Modal
   palette      generate or validate a semantic palette role contract
   verify       run automatable design-job steps and record evidence
   icon-glyph-check render icons and prove font load and glyph paint
+  app-collect  render an app route per viewport and write runtime evidence
   reference-ui, init, validate-ui, app-init, app-validate, rebrand, review
 """)
         return 0
-    if len(sys.argv) > 1 and sys.argv[1] in {"pressable-check", "layer-check"}:
+    if len(sys.argv) > 1 and sys.argv[1] in {"pressable-check", "layer-check", "safe-area-check"}:
         from maggie_design_lint import main as lint_main
         return lint_main(sys.argv[1:])
     if len(sys.argv) > 1 and sys.argv[1] == "verify":
         from maggie_design_verify import main as verify_main
         return verify_main(sys.argv[2:])
+    if len(sys.argv) > 1 and sys.argv[1] == "app-collect":
+        from maggie_app_collect import main as app_collect_main
+        return app_collect_main(sys.argv[2:])
     if len(sys.argv) > 1 and sys.argv[1] == "icon-glyph-check":
         from maggie_icon_glyph_check import main as glyph_main
         return glyph_main(sys.argv[2:])
@@ -924,11 +1077,21 @@ commands:
         command.add_argument("--project", type=Path, default=Path.cwd())
         command.add_argument("--route", required=True)
         command.add_argument("--auth-mode", choices=["email-password", "existing-session", "none"], default="email-password")
+        command.add_argument("--capabilities", help="none, or a comma list of camera,location,notifications,media-library (default camera)")
+        command.add_argument("--camera", choices=["required", "none"], help="shorthand: --camera none drops camera states")
+        command.add_argument("--pane", action="append", default=[], help="intentional multi-pane layout NAME:MIN_WIDTH:SCROLL_OWNERS, e.g. list-detail:1024:2")
+        command.add_argument("--viewport", action="append", default=[], help="override a plan viewport, e.g. tablet=768x1024")
+        command.add_argument("--pattern", action="append", default=[], choices=list(APP_PATTERNS), help="attach app UI pattern acceptance rules")
         command.add_argument("--force", action="store_true")
         command.add_argument("--confirm", action="store_true")
         args = command.parse_args(sys.argv[2:])
         try:
-            return app_surface_init(args.project, args.route, args.auth_mode, args.force, args.confirm)
+            capabilities = parse_app_capabilities(args.capabilities)
+            if args.camera == "none":
+                capabilities = [name for name in capabilities if name != "camera"]
+            elif args.camera == "required" and "camera" not in capabilities:
+                capabilities = ["camera"] + capabilities
+            return app_surface_init(args.project, args.route, args.auth_mode, args.force, args.confirm, capabilities, parse_app_panes(args.pane), parse_app_viewports(args.viewport), args.pattern)
         except (OSError, ValueError, json.JSONDecodeError) as error:
             print(f"BLOCKED: maggie-design app-init: {error}", file=sys.stderr); return 1
     if len(sys.argv) > 1 and sys.argv[1] == "app-validate":