@topy-ai/maggie 0.7.52 → 0.7.53

package/bundled-tools/clis/maggie_feedback.py

@@ -459,6 +459,12 @@ def collect_batch(args: argparse.Namespace) -> int:
     return 0
 
 
+AREA_SUBJECT_RE = re.compile(r"^([A-Za-z][A-Za-z0-9 /&._-]{0,30}):\s+(\S.*)$")
+SCOPE_RE = re.compile(r"^[a-z]+\(([^)]{1,40})\)!?:", re.IGNORECASE)
+SKILL_HINT_RE = re.compile(r"\b(?:maggie[\w-]*|skills?|cli|mcp|codex|claude)\b", re.IGNORECASE)
+SUMMARY_ITEM_CAP = 49
+
+
 def classify_subject(subject: str, include_all: bool) -> tuple[str, str] | None:
     """Return (type, text) for one commit subject, or ``None`` to skip it."""
     merge = MERGE_PR_RE.match(subject)
@@ -474,22 +480,58 @@ def classify_subject(subject: str, include_all: bool) -> tuple[str, str] | None:
         return "bug", subject
     if PLAIN_FEATURE_RE.search(subject):
         return "improvement", subject
+    # "Area: sentence" is how many product teams describe a change; it is a
+    # change in that area even when the sentence has no recognised verb.
+    if AREA_SUBJECT_RE.match(subject):
+        return "improvement", subject
     return ("general", subject) if include_all else None
 
 
-def _summary_repos(values: list[str]) -> list[tuple[str, Path]]:
-    """Parse ``--repo [LABEL=]PATH`` values; unlabeled repositories become repo1, repo2, ..."""
+def subject_scope(subject: str) -> str:
+    """The conventional-commit scope or ``Area:`` prefix of a subject, lower-cased; ``""`` when absent."""
+    match = SCOPE_RE.match(subject)
+    if match:
+        return match.group(1).strip().lower()
+    if FIX_SUBJECT_RE.match(subject) or FEATURE_SUBJECT_RE.match(subject) or CHORE_SUBJECT_RE.match(subject):
+        return ""
+    area = AREA_SUBJECT_RE.match(subject)
+    return area.group(1).strip().lower() if area else ""
+
+
+def _summary_repos(values: list[str], default_rev: str = "") -> list[tuple[str, Path, str]]:
+    """Parse ``--repo [LABEL=]PATH[@REV]`` values; unlabeled repositories become repo1, repo2, ..."""
     repos = []
     for index, value in enumerate(values or ["."], start=1):
         label, sep, path = value.partition("=")
         if not sep or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,40}", label):
             label, path = f"repo{index}", value
-        repos.append((label, Path(path).expanduser().resolve()))
-    if len({label for label, _ in repos}) != len(repos):
+        rev = default_rev
+        head, at, tail = path.rpartition("@")
+        if at and head and not Path(path).expanduser().exists():
+            path, rev = head, tail
+        if rev and (rev.startswith("-") or not re.fullmatch(r"[A-Za-z0-9._/@{}~^:-]{1,200}", rev)):
+            raise ValueError("revision must be a branch, tag or commit such as origin/main")
+        repos.append((label, Path(path).expanduser().resolve(), rev or "HEAD"))
+    if len({label for label, _, _ in repos}) != len(repos):
         raise ValueError("--repo labels must be unique")
     return repos
 
 
+def _behind_upstream(repo: Path, rev: str) -> tuple[str, int] | None:
+    """When reading HEAD, report (upstream, commits HEAD lacks) from local refs; never fetches."""
+    if rev != "HEAD":
+        return None
+    upstream = subprocess.run(["git", "-C", str(repo), "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{u}"], capture_output=True, text=True, check=False)
+    if upstream.returncode or not upstream.stdout.strip():
+        return None
+    count = subprocess.run(["git", "-C", str(repo), "rev-list", "--count", "HEAD..@{u}"], capture_output=True, text=True, check=False)
+    try:
+        behind = int(count.stdout.strip() or 0)
+    except ValueError:
+        return None
+    return (upstream.stdout.strip(), behind) if behind else None
+
+
 def session_summary(args: argparse.Namespace) -> int:
     """Draft a reviewable batch file from commit subjects; nothing is collected or submitted."""
     since = str(args.since or "").strip()
@@ -503,32 +545,53 @@ def session_summary(args: argparse.Namespace) -> int:
     batch_id = safe_text(args.batch_id) or f"session-{datetime.now(timezone.utc).strftime('%Y%m%d-%H%M%S')}"
     if not SAFE_BATCH_ID_RE.fullmatch(batch_id):
         raise ValueError("batch ID is invalid")
-    repos = _summary_repos(args.repo)
+    repos = _summary_repos(args.repo, str(getattr(args, "rev", "") or "").strip())
     include_all = bool(getattr(args, "all", False))
-    items = []
+    skill_relevant = bool(getattr(args, "skill_relevant", False))
+    skill_hint = safe_text(args.skill).lower().removeprefix("maggie-")
+    candidates = []
     skipped = 0
+    project_commits = 0
+    seen = 0
     per_repo = {}
-    for label, repo in repos:
+    warnings = []
+    for label, repo, rev in repos:
         command = ["git", "-C", str(repo), "log", "--format=%h%x1f%s"]
         if not getattr(args, "merges", False):
             command.append("--no-merges")
-        command += [f"--since={since_date}", "HEAD"] if since_date else [f"{since}..HEAD"]
+        command += [f"--since={since_date}", rev] if since_date else [f"{since}..{rev}"]
         completed = subprocess.run(command, capture_output=True, text=True, check=False)
         if completed.returncode:
-            raise ValueError(f"git log failed for {label}; check --repo and --since")
+            raise ValueError(f"git log failed for {label}; check --repo, --rev and --since")
+        lag = _behind_upstream(repo, rev)
+        if lag:
+            warnings.append(f"{label}: local HEAD is {lag[1]} commit(s) behind {lag[0]}; commits pushed from worktrees are missing. Re-run with --repo {label}=PATH@{lag[0]} (git fetch first).")
         counted = 0
         for line in completed.stdout.splitlines():
             sha, _, subject = line.partition("\x1f")
             subject = safe_text(subject)[:200]
             if not sha or not subject:
                 continue
+            seen += 1
             classified = classify_subject(subject, include_all)
             if classified is None:
                 skipped += 1
                 continue
+            scope = subject_scope(subject)
+            if skill_relevant and not (SKILL_HINT_RE.search(subject) or (skill_hint and skill_hint in subject.lower())):
+                project_commits += 1
+                continue
             kind, text = classified
             text = text[:1].upper() + text[1:] if text else subject
             commit = f"{label}@{sha}" if len(repos) > 1 else sha
+            candidates.append({"kind": kind, "text": text, "commit": commit, "scope": scope or label})
+            counted += 1
+        per_repo[label] = counted
+    grouped = len(candidates) > SUMMARY_ITEM_CAP
+    items = []
+    if not grouped:
+        for candidate in candidates:
+            commit, text, kind = candidate["commit"], candidate["text"], candidate["kind"]
             item = {
                 "type": kind,
                 "summary": text,
@@ -540,10 +603,24 @@ def session_summary(args: argparse.Namespace) -> int:
             if kind in {"bug", "improvement"}:
                 item.update({"fixed": True, "resolution": text})
             items.append(item)
-            counted += 1
-            if len(items) >= 49:
-                break
-        per_repo[label] = counted
+    else:
+        # Too many commits for one batch: one item per scope, so nothing is dropped silently.
+        scopes: dict[str, list[dict]] = {}
+        for candidate in candidates:
+            scopes.setdefault(candidate["scope"], []).append(candidate)
+        ordered = sorted(scopes.items(), key=lambda pair: (-len(pair[1]), pair[0]))
+        for scope, entries in ordered[:SUMMARY_ITEM_CAP]:
+            bugs = sum(1 for entry in entries if entry["kind"] == "bug")
+            items.append({
+                "type": "bug" if bugs * 2 > len(entries) else "improvement",
+                "summary": f"{scope}: {len(entries)} commit(s) ({bugs} fix) — keep only if a Maggie skill or CLI fell short",
+                "expected": f"{REVIEW_MARKER} what the skill or CLI should have done",
+                "actual": f"{REVIEW_MARKER} summarise the {scope} commits that came from a skill gap",
+                "validation": f"{REVIEW_MARKER} the test or check that verified the {scope} commits",
+                "evidence": [f"commit:{entry['commit']}" for entry in entries[:20]],
+            })
+        if len(ordered) > SUMMARY_ITEM_CAP:
+            warnings.append(f"{len(ordered) - SUMMARY_ITEM_CAP} scope(s) did not fit in one batch; narrow --since-date or use --skill-relevant.")
     items.append({
         "type": "feature",
         "summary": f"{REVIEW_MARKER} describe an open ask from this session, or delete this item",
@@ -557,6 +634,7 @@ def session_summary(args: argparse.Namespace) -> int:
         "phase": safe_text(args.phase) or "session-summary",
         "reviewRequired": True,
         "note": "Draft only. Remove items unrelated to Maggie skills or CLIs, replace every REVIEW: and delete the open-ask placeholder if unused. `maggie feedback batch` rejects unedited REVIEW: fields.",
+        "commits": {"seen": seen, "drafted": len(candidates), "skipped": skipped, "projectOnly": project_commits, "groupedByScope": grouped},
         "items": items,
     }
     project = Path(args.project).resolve()
@@ -567,7 +645,9 @@ def session_summary(args: argparse.Namespace) -> int:
         raise ValueError("output already exists; choose another --output or --batch-id")
     output.parent.mkdir(parents=True, exist_ok=True)
     output.write_text(json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
-    print(json.dumps({"status": "draft-written", "batchId": batch_id, "items": len(items), "skippedCommits": skipped, "repositories": per_repo, "output": str(output), "submitted": False}, ensure_ascii=False))
+    if grouped:
+        warnings.append(f"{len(candidates)} commits exceed the {SUMMARY_ITEM_CAP}-item batch limit, so they were grouped into one item per scope.")
+    print(json.dumps({"status": "draft-written", "batchId": batch_id, "items": len(items), "commitsSeen": seen, "draftedCommits": len(candidates), "skippedCommits": skipped, "projectOnlyCommits": project_commits, "groupedByScope": grouped, "repositories": per_repo, "warnings": warnings, "output": str(output), "submitted": False}, ensure_ascii=False))
     return 0
 
 
@@ -716,7 +796,9 @@ def main() -> int:
     summary_parser.add_argument("--project", default=argparse.SUPPRESS)
     summary_parser.add_argument("--since", default="", help="git revision; commits after it are summarized")
     summary_parser.add_argument("--since-date", default="", help="ISO date/time; use across several repositories")
-    summary_parser.add_argument("--repo", action="append", default=[], help="[LABEL=]PATH of a git repository; repeat for app, backend, edge (default: current directory)")
+    summary_parser.add_argument("--repo", action="append", default=[], help="[LABEL=]PATH[@REV] of a git repository; repeat for app, backend, edge (default: current directory at HEAD)")
+    summary_parser.add_argument("--rev", default="", help="revision to read in every repository without its own @REV, e.g. origin/main")
+    summary_parser.add_argument("--skill-relevant", action="store_true", help="keep only commits that mention Maggie, a skill, a CLI or MCP (or the --skill name); count the rest as project-only")
     summary_parser.add_argument("--all", action="store_true", help="also draft unclassified and chore subjects as general items")
     summary_parser.add_argument("--merges", action="store_true", help="include merge commits (PR branch names are classified)")
     summary_parser.add_argument("--batch-id", default="")

package/bundled-tools/clis/maggie_mobile.py

@@ -20,19 +20,32 @@ fails. It checks, per build profile and platform:
 
 ``plan`` prints the build / submit / update commands with a cost notice and
 never runs them. Nothing is uploaded and no credentials are read.
+
+An OTA update must be fingerprinted with the config files the store build was
+made from: ``eas.json`` and ``package.json`` usually changed since. ``plan
+--build-ref <git ref>`` adds the swap steps, and ``ota --build-ref REF
+--build-id ID`` performs them: put the build commit's copies in place, run
+``eas fingerprint:compare``, publish the update only when it matches, and
+always put the working copies back (verified by hash), even on failure. ``ota``
+is a dry run unless ``--confirm`` is given, because the update is published.
 """
 
 from __future__ import annotations
 
 import argparse
+import hashlib
 import json
+import os
 import re
+import shlex
+import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
 
 SCHEMA = "maggie-mobile-release-preflight.v1"
 PLATFORMS = ("ios", "android")
+BUILD_CONFIG_FILES = ("eas.json", "package.json")
 VERSION_POLICIES = {"appVersion", "nativeVersion", "sdkVersion"}
 
 
@@ -185,7 +198,33 @@ def cost_notice(platforms: list[str], profile: str) -> str:
             "build minutes even if a later step fails. EAS Update publishes are counted against monthly update users. Confirm before running.")
 
 
-def plan_commands(profile: str, platforms: list[str], auto_submit: bool, channel: str | None, environment: str | None = None) -> list[dict]:
+def git_root(path: Path) -> Path:
+    completed = subprocess.run(["git", "-C", str(path), "rev-parse", "--show-toplevel"], capture_output=True, text=True, check=False)
+    if completed.returncode:
+        raise ValueError("the app folder is not inside a git repository; --build-ref needs git")
+    return Path(completed.stdout.strip()).resolve()
+
+
+def build_config_drift(app: Path, build_ref: str) -> list[dict]:
+    """Config files whose working copy differs from the build commit's copy (git object paths, never contents)."""
+    if build_ref.startswith("-") or not re.fullmatch(r"[A-Za-z0-9._/@{}~^:-]{1,200}", build_ref):
+        raise ValueError("--build-ref must be a git revision such as a tag or commit")
+    root = git_root(app)
+    files = []
+    for name in BUILD_CONFIG_FILES:
+        path = app / name
+        rel = path.resolve().relative_to(root).as_posix()
+        shown = subprocess.run(["git", "-C", str(root), "show", f"{build_ref}:{rel}"], capture_output=True, check=False)
+        if shown.returncode:
+            if name == "eas.json":
+                raise ValueError(f"{rel} does not exist at {build_ref}; is that the commit the store build was made from?")
+            continue
+        current = path.read_bytes() if path.is_file() else b""
+        files.append({"file": rel, "differs": current != shown.stdout, "buildBytes": shown.stdout, "workingSha256": hashlib.sha256(current).hexdigest()})
+    return files
+
+
+def plan_commands(profile: str, platforms: list[str], auto_submit: bool, channel: str | None, environment: str | None = None, build_ref: str | None = None, drift: list[dict] | None = None) -> list[dict]:
     environment = environment or (profile if profile in {"development", "preview", "production"} else "production")
     platform_arg = "all" if len(platforms) == 2 else platforms[0]
     commands = [{"step": "preflight", "command": f"maggie mobile preflight --profile {profile} --platform {platform_arg}" + (" --auto-submit" if auto_submit else ""), "spends": False}]
@@ -194,16 +233,81 @@ def plan_commands(profile: str, platforms: list[str], auto_submit: bool, channel
     if not auto_submit:
         for platform in platforms:
             commands.append({"step": f"submit-{platform}", "command": f"npx eas-cli submit -p {platform} --profile {profile} --latest --non-interactive", "spends": False})
+    swapped = [item["file"] for item in (drift or []) if item["differs"]]
+    if channel and build_ref:
+        commands.append({"step": "ota-from-build-config", "command": f"maggie mobile ota --profile {profile} --platform {platform_arg} --build-ref {build_ref} --build-id <installed build id> --message \"<what changed>\" --confirm", "spends": True,
+                         "note": ("swaps " + ", ".join(swapped) + f" for the copies at {build_ref}, runs fingerprint:compare and the update, then restores the working copies" if swapped else f"the config files match {build_ref}; no swap needed")})
+        return commands
     if channel:
         commands.append({"step": "fingerprint-gate", "command": "npx eas-cli fingerprint:compare --build-id <installed build id>", "spends": False, "note": "must report no difference; editing eas.json, native config or dependencies after the build changes the fingerprint and the update would reach no installed build"})
         commands.append({"step": "ota-update", "command": f"npx eas-cli update --channel {channel} --environment {environment} --platform {platform_arg} --message \"<what changed>\" --non-interactive", "spends": True, "note": "only JS/asset changes; a native change needs a new build (the fingerprint policy enforces this)"})
     return commands
 
 
+def eas_command() -> list[str]:
+    """The EAS CLI invocation; MAGGIE_MOBILE_EAS overrides it (tests, a pinned eas-cli)."""
+    return shlex.split(os.environ.get("MAGGIE_MOBILE_EAS", "npx eas-cli"))
+
+
+def fingerprint_hashes(stdout: str) -> tuple[str, str] | None:
+    """(build hash, project hash) from `eas fingerprint:compare --json`, or None when the output is not that."""
+    start = stdout.find("{")
+    try:
+        data = json.loads(stdout[start:]) if start >= 0 else {}
+        return str(data["fingerprint1"]["hash"]), str(data["fingerprint2"]["hash"])
+    except (ValueError, KeyError, TypeError):
+        return None
+
+
+def ota(app: Path, build_ref: str, build_id: str, channel: str, environment: str, platform_arg: str, message: str, confirm: bool) -> dict:
+    """Fingerprint and publish an update with the build's own config files; always restore the working copies."""
+    if not re.fullmatch(r"[A-Za-z0-9-]{8,64}", build_id):
+        raise ValueError("--build-id must be the EAS build id of the installed build")
+    if not message.strip():
+        raise ValueError("--message is required")
+    drift = build_config_drift(app, build_ref)
+    root = git_root(app)
+    # fingerprint:compare exits 0 even when the fingerprints differ; --json prints both, so compare the hashes.
+    compare = eas_command() + ["fingerprint:compare", "--build-id", build_id, "--json", "--non-interactive"]
+    update = eas_command() + ["update", "--channel", channel, "--environment", environment, "--platform", platform_arg, "--message", message, "--non-interactive"]
+    report = {"buildRef": build_ref, "swapped": [item["file"] for item in drift if item["differs"]], "commands": [shlex.join(compare), shlex.join(update)], "executed": False}
+    if not confirm:
+        report["status"] = "dry-run"
+        report["note"] = "nothing was changed; re-run with --confirm to swap, compare, publish and restore"
+        return report
+    originals = {item["file"]: (root / item["file"]).read_bytes() for item in drift if item["differs"]}
+    steps = []
+    try:
+        for item in drift:
+            if item["differs"]:
+                (root / item["file"]).write_bytes(item["buildBytes"])
+        result = subprocess.run(compare, cwd=app, capture_output=True, text=True, check=False)
+        hashes = fingerprint_hashes(result.stdout)
+        steps.append({"step": "fingerprint-compare", "exit": result.returncode, "match": bool(hashes) and hashes[0] == hashes[1]})
+        if result.returncode or not hashes:
+            report.update(status="failed", reason="fingerprint:compare did not return two fingerprints; nothing was published")
+            return report
+        if hashes[0] != hashes[1]:
+            report.update(status="failed", reason="the fingerprint with the build's config files does not match the installed build; this change needs a new native build")
+            return report
+        result = subprocess.run(update, cwd=app, capture_output=True, text=True, check=False)
+        steps.append({"step": "update", "exit": result.returncode})
+        report["executed"] = True
+        report["status"] = "published" if result.returncode == 0 else "failed"
+        if result.returncode:
+            report["reason"] = "eas update failed; see its output"
+        return report
+    finally:
+        for rel, data in originals.items():
+            (root / rel).write_bytes(data)
+        report["restored"] = {rel: hashlib.sha256((root / rel).read_bytes()).hexdigest() == hashlib.sha256(data).hexdigest() for rel, data in originals.items()}
+        report["steps"] = steps
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="maggie mobile", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
     sub = parser.add_subparsers(dest="command", required=True)
-    for name in ("preflight", "plan"):
+    for name in ("preflight", "plan", "ota"):
         command = sub.add_parser(name)
         command.add_argument("--project", type=Path, default=Path("."))
         command.add_argument("--app-dir", type=Path, help="Expo app folder inside a monorepo, e.g. apps/app")
@@ -213,6 +317,12 @@ def main(argv: list[str] | None = None) -> int:
         command.add_argument("--auto-submit", action="store_true", help="the build will run with --auto-submit --non-interactive")
         command.add_argument("--environment", help="EAS environment for updates (default: the profile when it is development/preview/production)")
         command.add_argument("--output", type=Path)
+        if name in {"plan", "ota"}:
+            command.add_argument("--build-ref", help="git commit or tag the installed store build was made from")
+        if name == "ota":
+            command.add_argument("--build-id", required=True, help="EAS build id of the installed build (for fingerprint:compare)")
+            command.add_argument("--message", required=True)
+            command.add_argument("--confirm", action="store_true", help="actually swap, compare, publish and restore; without it nothing changes")
     args = parser.parse_args(argv)
     platforms = list(PLATFORMS) if args.platform == "all" else [args.platform]
     try:
@@ -220,14 +330,36 @@ def main(argv: list[str] | None = None) -> int:
     except (OSError, ValueError) as error:
         print(f"BLOCKED: maggie mobile {args.command}: {error}", file=sys.stderr)
         return 2
-    if args.command == "plan":
-        report = {"schemaVersion": "maggie-mobile-release-plan.v1", "preflight": {key: report[key] for key in ("status", "errors", "warnings")}, "commands": plan_commands(args.profile, platforms, args.auto_submit, report["facts"].get("channel") if report["facts"].get("easUpdate") else None, args.environment), "costNotice": report["costNotice"], "executed": False}
+    project = args.project.resolve()
+    app = (project / args.app_dir).resolve() if args.app_dir and not args.app_dir.is_absolute() else (args.app_dir.resolve() if args.app_dir else project)
+    channel = report["facts"].get("channel") if report["facts"].get("easUpdate") else None
+    environment = args.environment or (args.profile if args.profile in {"development", "preview", "production"} else "production")
+    platform_arg = "all" if len(platforms) == 2 else platforms[0]
+    try:
+        if args.command == "plan":
+            drift = build_config_drift(app, args.build_ref) if args.build_ref else None
+            report = {"schemaVersion": "maggie-mobile-release-plan.v1", "preflight": {key: report[key] for key in ("status", "errors", "warnings")}, "commands": plan_commands(args.profile, platforms, args.auto_submit, channel, args.environment, args.build_ref, drift), "costNotice": report["costNotice"], "executed": False}
+            if drift is not None:
+                report["buildConfig"] = [{"file": item["file"], "differsFromBuild": item["differs"]} for item in drift]
+        elif args.command == "ota":
+            if report["status"] == "failed":
+                raise ValueError("preflight failed: " + "; ".join(report["errors"]))
+            if not channel:
+                raise ValueError("the profile has no EAS Update channel")
+            if not args.build_ref:
+                raise ValueError("--build-ref is required: the commit the installed build was made from")
+            report = {"schemaVersion": "maggie-mobile-ota.v1", **ota(app, args.build_ref, args.build_id, channel, environment, platform_arg, args.message, args.confirm)}
+    except (OSError, ValueError) as error:
+        print(f"BLOCKED: maggie mobile {args.command}: {error}", file=sys.stderr)
+        return 2
     text = json.dumps(report, indent=2, ensure_ascii=False)
     if args.output:
         args.output.parent.mkdir(parents=True, exist_ok=True)
         args.output.write_text(text + "\n", encoding="utf-8")
     print(text)
     status = report["status"] if "status" in report else report["preflight"]["status"]
+    if report.get("restored") and not all(report["restored"].values()):
+        return 1
     return 1 if status == "failed" else 0
 
 

package/bundled-tools/clis/maggie_qa_app_preflight.py

@@ -12,6 +12,13 @@ broken change or quietly damaged real data:
   (iframes, tabs, parallel viewports) refresh at once, and a local dev server
   that talks to a production API turns QA clicks into production writes.
 
+Two more failures hid stale code: a dev server killed and replaced by another
+session's server on the same port, and a watcher that kept serving the old
+bundle after edits. ``--expect-symbol NAME`` fetches the served entry bundle
+from ``--base-url`` and fails when it lacks a name from the edit just made;
+the report also names the process holding the base URL's port and when it
+started, so a server restarted by someone else is obvious.
+
 The command inspects running dev-server processes (Linux ``/proc``; other
 systems fall back to ``ps``), the app's environment files and auth code, and
 reports environment variable names and host classes only — never values,
@@ -28,7 +35,8 @@ import subprocess
 import sys
 from datetime import datetime, timezone
 from pathlib import Path
-from urllib.parse import urlsplit
+from urllib.parse import urljoin, urlsplit
+from urllib.request import Request, urlopen
 
 SCHEMA = "maggie-qa-app-preflight.v1"
 DEV_SERVER = re.compile(r"(expo(?:/cli)?[^ ]*\s+start|@expo/cli.*\bstart\b|react-native\s+start|metro(?:\.js)?\s|node_modules/\.bin/metro|expo-router)", re.I)
@@ -78,6 +86,84 @@ def list_processes() -> list[dict]:
     return found
 
 
+def process_started_at(pid: int) -> str | None:
+    """ISO start time of a Linux process from /proc/<pid>/stat and the boot time; None elsewhere."""
+    try:
+        stat = Path(f"/proc/{pid}/stat").read_text(encoding="utf-8")
+        ticks = int(stat.rsplit(")", 1)[1].split()[19])
+        boot = next(int(line.split()[1]) for line in Path("/proc/stat").read_text(encoding="utf-8").splitlines() if line.startswith("btime "))
+        return datetime.fromtimestamp(boot + ticks / os.sysconf("SC_CLK_TCK"), timezone.utc).isoformat(timespec="seconds")
+    except (OSError, ValueError, IndexError, StopIteration):
+        return None
+
+
+def port_owner(port: int) -> dict | None:
+    """The process listening on a TCP port (Linux /proc); command line trimmed to the program and script."""
+    inodes = set()
+    for table in ("/proc/net/tcp", "/proc/net/tcp6"):
+        try:
+            lines = Path(table).read_text(encoding="utf-8").splitlines()[1:]
+        except OSError:
+            continue
+        for line in lines:
+            fields = line.split()
+            if len(fields) > 9 and fields[3] == "0A" and int(fields[1].rsplit(":", 1)[1], 16) == port:
+                inodes.add(fields[9])
+    if not inodes:
+        return None
+    for entry in Path("/proc").iterdir():
+        if not entry.name.isdigit():
+            continue
+        links = set()
+        try:
+            descriptors = list((entry / "fd").iterdir())
+        except OSError:
+            continue
+        for fd in descriptors:
+            try:
+                links.add(os.readlink(fd))
+            except OSError:
+                continue
+        if any(f"socket:[{inode}]" in links for inode in inodes):
+            try:
+                cmdline = (entry / "cmdline").read_bytes().replace(b"\0", b" ").decode("utf-8", "replace").strip()
+                cwd = os.readlink(entry / "cwd")
+            except OSError:
+                cmdline, cwd = "", None
+            return {"pid": int(entry.name), "command": " ".join(cmdline.split()[:3])[:160], "cwd": cwd, "startedAt": process_started_at(int(entry.name))}
+    return {"pid": None, "command": "unknown (owned by another user)", "cwd": None, "startedAt": None}
+
+
+SCRIPT_SRC = re.compile(r"<script[^>]+src=[\"']([^\"']+)[\"']", re.I)
+
+
+def _fetch(url: str, limit: int) -> bytes:
+    request = Request(url, headers={"User-Agent": "maggie-qa-app-preflight"})
+    with urlopen(request, timeout=60) as response:  # noqa: S310 - local dev server URL given by the operator
+        return response.read(limit)
+
+
+def bundle_symbols(base_url: str, symbols: list[str], limit: int = 80_000_000) -> dict:
+    """Fetch the page at base_url and its same-origin scripts; report which expected names they contain."""
+    origin = urlsplit(base_url)
+    html = _fetch(base_url, 5_000_000).decode("utf-8", "replace")
+    scripts = []
+    for src in SCRIPT_SRC.findall(html):
+        url = urljoin(base_url, src)
+        if urlsplit(url).netloc == origin.netloc:
+            scripts.append(url)
+    found: dict[str, list[str]] = {symbol: [] for symbol in symbols}
+    fetched = []
+    for url in scripts[:12]:
+        body = _fetch(url, limit).decode("utf-8", "replace")
+        path = urlsplit(url).path
+        fetched.append({"path": path, "bytes": len(body)})
+        for symbol in symbols:
+            if symbol in body:
+                found[symbol].append(path)
+    return {"scripts": fetched, "found": {symbol: bool(paths) for symbol, paths in found.items()}, "foundIn": found}
+
+
 def find_app_dirs(project: Path) -> list[Path]:
     """Expo apps in the project: the root itself, or monorepo apps/* and packages/*."""
     candidates = [project] + sorted(path for pattern in ("apps/*", "packages/*") for path in project.glob(pattern) if path.is_dir())
@@ -158,7 +244,7 @@ def refresh_token_signals(app_dir: Path, limit: int = 4000) -> dict:
     return {"filesScanned": files, "refreshTokenFiles": refresh, "rotationHintFiles": rotation, "examples": examples}
 
 
-def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotating: str, processes: list[dict] | None = None) -> dict:
+def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotating: str, processes: list[dict] | None = None, expect_symbols: list[str] | None = None) -> dict:
     project = project.resolve()
     errors: list[str] = []
     warnings: list[str] = []
@@ -174,7 +260,7 @@ def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotatin
     for item in (list_processes() if processes is None else processes):
         cwd = item.get("cwd")
         command = item.get("cmdline", "")
-        record = {"pid": item.get("pid"), "cwd": rel(cwd) if cwd else None, "ciMode": bool(item.get("ci")), "noWatch": "--no-watch" in command}
+        record = {"pid": item.get("pid"), "cwd": rel(cwd) if cwd else None, "ciMode": bool(item.get("ci")), "noWatch": "--no-watch" in command, "startedAt": item.get("startedAt") or (process_started_at(item["pid"]) if isinstance(item.get("pid"), int) else None)}
         if cwd and not Path(cwd).resolve().is_relative_to(project):
             record["scope"] = "other project"
             servers.append(record)
@@ -189,6 +275,35 @@ def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotatin
     in_project = [server for server in servers if server.get("scope") != "other project"]
     if not in_project:
         warnings.append("no running Metro/Expo dev server found for this project; start one from the app folder without CI=1")
+    owner = None
+    if base_url:
+        parts = urlsplit(base_url)
+        port = parts.port or (443 if parts.scheme == "https" else 80)
+        if classify_host(base_url) == "local":
+            owner = port_owner(port)
+            if owner is None:
+                errors.append(f"nothing is listening on port {port}; the dev server was stopped or killed (check for exit 137) — start it from {rel(app_dir)}")
+            else:
+                owner = {**owner, "port": port, "cwd": rel(owner["cwd"]) if owner.get("cwd") else None}
+                known = {server["pid"] for server in in_project}
+                if owner["pid"] is not None and owner["pid"] not in known:
+                    where = owner["cwd"] or "an unknown folder"
+                    errors.append(f"port {port} is held by pid {owner['pid']} ({owner['command']}, started {owner['startedAt'] or 'unknown'}) from {where}, not by a dev server of {rel(app_dir)}; another session may have replaced it")
+    bundle = None
+    if expect_symbols:
+        if not base_url:
+            errors.append("--expect-symbol needs --base-url to fetch the served bundle")
+        else:
+            try:
+                bundle = bundle_symbols(base_url, expect_symbols)
+            except (OSError, ValueError) as error:
+                errors.append(f"could not fetch the served bundle from --base-url: {error}")
+            else:
+                if not bundle["scripts"]:
+                    errors.append("the page at --base-url has no same-origin script, so the served bundle could not be checked")
+                missing = [symbol for symbol, ok in bundle["found"].items() if not ok]
+                if bundle["scripts"] and missing:
+                    errors.append("the served bundle does not contain " + ", ".join(missing) + ": the dev server is serving old code (stale watcher, wrong folder or another session's server); restart it before QA")
     signals = refresh_token_signals(app_dir)
     rotating_tokens = rotating == "yes" or (rotating == "auto" and signals["refreshTokenFiles"] > 0)
     if rotating_tokens:
@@ -213,6 +328,8 @@ def preflight(project: Path, app_dir: Path | None, base_url: str | None, rotatin
         "appDir": rel(app_dir),
         "appCandidates": [rel(path) for path in apps],
         "devServers": servers,
+        "portOwner": owner,
+        "servedBundle": bundle,
         "refreshTokens": {"rotating": rotating_tokens, "source": rotating, **signals},
         "apiTargets": targets,
         "status": "failed" if errors else ("warning" if warnings else "passed"),
@@ -229,10 +346,11 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("--app-dir", type=Path, help="app folder inside a monorepo, e.g. apps/app")
     parser.add_argument("--base-url", help="URL the browser QA will open")
     parser.add_argument("--rotating-refresh-tokens", choices=("auto", "yes", "no"), default="auto")
+    parser.add_argument("--expect-symbol", action="append", default=[], metavar="NAME", help="a name from the edit just made (component, string, export); fails when the served bundle lacks it")
     parser.add_argument("--output", type=Path)
     args = parser.parse_args(argv)
     try:
-        report = preflight(args.project, args.app_dir, args.base_url, args.rotating_refresh_tokens)
+        report = preflight(args.project, args.app_dir, args.base_url, args.rotating_refresh_tokens, expect_symbols=args.expect_symbol)
     except (OSError, ValueError) as error:
         print(f"BLOCKED: maggie qa app-preflight: {error}", file=sys.stderr)
         return 2