@sitar_fiercer4c/skills 0.1.0

package/skills/record-api-traffic/scripts/record-api-traffic.py

@@ -0,0 +1,720 @@
+#!/usr/bin/env python3
+"""Record every HTTP call a Node/Next app makes, on all four legs.
+
+Run it with the repo path, open the link it prints, use the app, Ctrl-C.
+Each leg gets an aligned table to scan and a JSONL file with full
+request/response bodies.
+
+Both servers are recorded the same way: a mitmdump reverse proxy takes the
+port the browser already calls, and the server moves one port up behind it,
+so nothing on the VS Code side and no config file in the repo has to change.
+
+    browser  -> :4100 recorder -> :4101 frontend   frontend-inbound.*
+    browser  -> :7100 recorder -> :7101 backend    backend-inbound.*
+
+Each server also gets a mitmdump in regular (forward) mode recording the
+calls it makes itself, from Node rather than the browser:
+
+    frontend -> :4102 recorder -> the backend, and anything external
+    backend  -> :7102 recorder -> Microsoft Graph, Datalab
+
+--no-frontend drops the frontend legs, --no-outbound drops both forward
+proxies, --frontend-all keeps the static-asset noise the frontend leg
+discards by default.
+
+Nothing is written inside the repo. The backend's scratch working directory
+is a temp dir, and recordings land in this skill's own workspace.
+
+This file plays two roles. Run directly, it orchestrates. Loaded by
+mitmdump via -s, it is the recording addon.
+"""
+
+import argparse
+import json
+import os
+import re
+import shutil
+import signal
+import socket
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import urllib.error
+import urllib.request
+from collections import deque
+from datetime import datetime
+from pathlib import Path
+
+SKILL = Path(__file__).resolve().parent.parent
+WORKSPACE = SKILL.parent / "record-api-traffic-workspace" / "recordings"
+
+PROXY_PORT = 7100
+BACKEND_PORT = 7101
+OUTBOUND_PORT = 7102
+FRONTEND_PROXY_PORT = 4100
+FRONTEND_PORT = 4101
+FRONTEND_OUTBOUND_PORT = 4102
+
+SCRATCH_PREFIX = "record-api-traffic-"
+
+# Every child is started with this in its environment, so a leftover process
+# from a crashed run can be told apart from the app's own dev server even
+# though the frontend has to run with its real working directory.
+CHILD_MARKER = "RECORD_API_TRAFFIC_RUN"
+
+# Build output and dev-server plumbing on the frontend leg. One page load in
+# `next dev` pulls dozens of chunks, each recorded in full would bury the
+# handful of rows that carry meaning -- navigations, RSC payloads, server
+# actions and any route handler the frontend serves itself.
+FRONTEND_NOISE = r"^/(?:_next/static/|_next/image|_next/webpack-hmr|__nextjs|favicon\.ico$)"
+
+MITM_CA = Path.home() / ".mitmproxy" / "mitmproxy-ca-cert.pem"
+
+MAX_BODY = 1024 * 1024
+
+BINARY_TYPES = (
+    "image/",
+    "audio/",
+    "video/",
+    "font/",
+    "application/pdf",
+    "application/zip",
+    "application/octet-stream",
+    "application/vnd.openxmlformats",
+    "application/vnd.ms-excel",
+)
+
+ROW_FMT = "{ts:<12}  {id:<4} {ms:>6}  {method:<6} {status:<6} {path:<44} {req:>9}  {resp:>9}"
+HEADER = ROW_FMT.format(
+    ts="TIME", id="ID", ms="MS", method="METHOD", status="STATUS",
+    path="PATH", req="REQ", resp="RESP",
+)
+
+
+def human_size(n):
+    if n is None:
+        return "-"
+    if n == 0:
+        return "-"
+    if n < 1024:
+        return f"{n} B"
+    if n < 1024 * 1024:
+        return f"{n / 1024:.1f} KB"
+    return f"{n / (1024 * 1024):.1f} MB"
+
+
+def workspace_slug(repo):
+    """Last two path segments, so two clones of the same repo stay apart."""
+    parts = [p for p in repo.parts if p not in ("/", "")][-2:]
+    return re.sub(r"[^a-z0-9]+", "-", "-".join(parts).lower()).strip("-")
+
+
+# --------------------------------------------------------------------------
+# Recorder — active only inside the mitmdump child process.
+# --------------------------------------------------------------------------
+
+class Recorder:
+    def __init__(self):
+        self.jsonl_path = os.environ["MITM_RECORD_JSONL"]
+        self.log_path = os.environ["MITM_RECORD_LOG"]
+        self.show_host = bool(os.environ.get("MITM_RECORD_SHOW_HOST"))
+        skip = os.environ.get("MITM_RECORD_SKIP")
+        self.skip = re.compile(skip) if skip else None
+        self.jsonl = None
+        self.log = None
+        self.counter = 0
+
+    def running(self):
+        self.jsonl = open(self.jsonl_path, "a", encoding="utf-8")
+        self.log = open(self.log_path, "a", encoding="utf-8")
+        self.log.write(HEADER + "\n")
+        self.log.flush()
+
+    def done(self):
+        for handle in (self.jsonl, self.log):
+            if handle:
+                handle.close()
+
+    def response(self, flow):
+        self._record(flow, None)
+
+    def error(self, flow):
+        if flow.response is None:
+            self._record(flow, str(flow.error) if flow.error else "connection error")
+
+    def _record(self, flow, error):
+        req = flow.request
+        # Before the counter moves, so a dropped call leaves no gap and the
+        # row ID stays equal to the line number in the JSONL.
+        if self.skip and self.skip.search(req.path.split("?")[0]):
+            return
+
+        self.counter += 1
+        rec_id = f"{self.counter:04d}"
+
+        resp = flow.response
+
+        started = req.timestamp_start
+        ended = (resp.timestamp_end if resp and resp.timestamp_end else time.time())
+        duration_ms = int((ended - started) * 1000)
+
+        req_body, req_size = self._body(req)
+        if resp is not None:
+            resp_body, resp_size = self._body(resp)
+        else:
+            resp_body, resp_size = None, 0
+
+        record = {
+            "id": rec_id,
+            "ts": datetime.fromtimestamp(ended).astimezone().isoformat(),
+            "started_at": datetime.fromtimestamp(started).astimezone().isoformat(),
+            "duration_ms": duration_ms,
+            "method": req.method,
+            "path": req.path.split("?")[0],
+            "host": req.pretty_host,
+            "url": req.pretty_url,
+            "query": dict(req.query),
+            "client_ip": flow.client_conn.peername[0] if flow.client_conn.peername else None,
+            "request": {
+                "headers": dict(req.headers),
+                "body": req_body["value"],
+                "body_encoding": req_body["encoding"],
+                "body_size": req_size,
+                "truncated": req_body["truncated"],
+            },
+        }
+        if resp is not None:
+            record["response"] = {
+                "status": resp.status_code,
+                "headers": dict(resp.headers),
+                "body": resp_body["value"],
+                "body_encoding": resp_body["encoding"],
+                "body_size": resp_size,
+                "truncated": resp_body["truncated"],
+            }
+        if error:
+            record["error"] = error
+
+        self.jsonl.write(json.dumps(record, ensure_ascii=False, default=str) + "\n")
+        self.jsonl.flush()
+
+        path = req.path
+        if self.show_host:
+            # With the port: a forward-proxy leg spans hosts, and on the
+            # frontend's it also spans loopback ports, where :7100 (the
+            # backend) and :4101 (the frontend calling itself) are otherwise
+            # the same "127.0.0.1".
+            host = req.pretty_host
+            if req.port != (443 if req.scheme == "https" else 80):
+                host = f"{host}:{req.port}"
+            path = f"{host}{req.path}"
+        if len(path) > 44:
+            path = path[:43] + "…"
+        self.log.write(ROW_FMT.format(
+            ts=datetime.fromtimestamp(ended).strftime("%H:%M:%S.%f")[:-3],
+            id=rec_id,
+            ms=duration_ms,
+            method=req.method,
+            status=str(resp.status_code) if resp is not None else "ERR",
+            path=path,
+            req=human_size(req_size),
+            resp=human_size(resp_size) if resp is not None else "-",
+        ) + "\n")
+        self.log.flush()
+
+    def _body(self, message):
+        """Return ({value, encoding, truncated}, size) for a request or response."""
+        empty = {"value": None, "encoding": None, "truncated": False}
+        try:
+            content = message.get_content(strict=False)
+        except Exception:
+            content = message.raw_content
+        if not content:
+            return empty, 0
+
+        size = len(content)
+        ctype = message.headers.get("content-type", "").lower()
+
+        if any(ctype.startswith(t) for t in BINARY_TYPES):
+            return {
+                "value": {"binary": True, "content_type": ctype or None, "size": size},
+                "encoding": "binary",
+                "truncated": False,
+            }, size
+
+        truncated = size > MAX_BODY
+        text = content[:MAX_BODY].decode("utf-8", errors="replace")
+        if truncated:
+            return {"value": text, "encoding": "text", "truncated": True}, size
+
+        try:
+            return {"value": json.loads(text), "encoding": "json", "truncated": False}, size
+        except (ValueError, TypeError):
+            return {"value": text, "encoding": "text", "truncated": False}, size
+
+
+if os.environ.get("MITM_RECORD_JSONL"):
+    addons = [Recorder()]
+
+
+# --------------------------------------------------------------------------
+# Launcher
+# --------------------------------------------------------------------------
+
+class Child:
+    def __init__(self, name, argv, cwd, env=None):
+        self.name = name
+        self.tail = deque(maxlen=40)
+        env = dict(env or os.environ)
+        env[CHILD_MARKER] = str(os.getpid())
+        self.proc = subprocess.Popen(
+            argv,
+            cwd=str(cwd),
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+            start_new_session=True,
+        )
+        threading.Thread(target=self._pump, daemon=True).start()
+
+    def _pump(self):
+        for line in self.proc.stdout:
+            line = line.rstrip()
+            self.tail.append(line)
+            print(f"[{self.name}] {line}", flush=True)
+
+    def alive(self):
+        return self.proc.poll() is None
+
+    def stop(self):
+        if self.proc.poll() is not None:
+            return
+        try:
+            pgid = os.getpgid(self.proc.pid)
+        except ProcessLookupError:
+            return
+        for sig in (signal.SIGTERM, signal.SIGKILL):
+            try:
+                os.killpg(pgid, sig)
+            except ProcessLookupError:
+                return
+            deadline = time.time() + 10
+            while time.time() < deadline:
+                if self.proc.poll() is not None:
+                    return
+                time.sleep(0.2)
+
+
+children = []
+scratch = None
+cleaned = False
+
+
+def port_in_use(port):
+    with socket.socket() as s:
+        s.settimeout(0.5)
+        return s.connect_ex(("127.0.0.1", port)) == 0
+
+
+def port_holder(port):
+    try:
+        out = subprocess.run(
+            ["ss", "-ltnp", f"sport = :{port}"],
+            capture_output=True, text=True, timeout=5,
+        ).stdout
+        match = re.search(r'users:\(\("([^"]+)",pid=(\d+)', out)
+        if match:
+            return f"{match.group(1)} (pid {match.group(2)})"
+    except Exception:
+        pass
+    return "unknown process"
+
+
+def wait_for_http(url, timeout, child=None):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if child and not child.alive():
+            return False
+        try:
+            with urllib.request.urlopen(url, timeout=3) as r:
+                if r.status < 500:
+                    return True
+        except urllib.error.HTTPError as e:
+            if e.code < 500:
+                return True
+        except Exception:
+            pass
+        time.sleep(0.5)
+    return False
+
+
+def wait_for_port(port, timeout, child=None):
+    deadline = time.time() + timeout
+    while time.time() < deadline:
+        if child and not child.alive():
+            return False
+        if port_in_use(port):
+            return True
+        time.sleep(0.5)
+    return False
+
+
+def die(message, child=None):
+    print(f"\n  ERROR: {message}\n", file=sys.stderr)
+    if child and child.tail:
+        print(f"  last output from {child.name}:", file=sys.stderr)
+        for line in child.tail:
+            print(f"    {line}", file=sys.stderr)
+        print(file=sys.stderr)
+    cleanup()
+    sys.exit(1)
+
+
+def cleanup(*_):
+    global cleaned
+    if cleaned:
+        return
+    cleaned = True
+    print("\n  Shutting down...", flush=True)
+    for child in reversed(children):
+        child.stop()
+    if scratch:
+        shutil.rmtree(scratch, ignore_errors=True)
+
+
+def preflight(repo, outbound, record_frontend):
+    backend, frontend = repo / "Backend", repo / "Frontend"
+    if not shutil.which("mitmdump"):
+        die("mitmdump not found on PATH. Install with: pipx install mitmproxy")
+    for path in (backend / ".env", frontend / ".env.local",
+                 backend / "node_modules", frontend / "node_modules"):
+        if not path.exists():
+            die(f"missing {path}")
+    ports = [(PROXY_PORT, "backend proxy"), (BACKEND_PORT, "backend"),
+             (FRONTEND_PROXY_PORT, "frontend proxy" if record_frontend else "frontend")]
+    if outbound:
+        ports.append((OUTBOUND_PORT, "backend outbound proxy"))
+    if record_frontend:
+        ports.append((FRONTEND_PORT, "frontend"))
+        if outbound:
+            ports.append((FRONTEND_OUTBOUND_PORT, "frontend outbound proxy"))
+    for port, what in ports:
+        if port_in_use(port):
+            die(f"port {port} ({what}) is already in use by {port_holder(port)}. "
+                "Stop it and re-run.")
+    if outbound and not MITM_CA.exists():
+        die(f"missing {MITM_CA}. mitmproxy writes it on its first run; start "
+            "mitmdump once, or pass --no-outbound.")
+
+
+def dev_script(frontend):
+    try:
+        pkg = json.loads((frontend / "package.json").read_text())
+    except (OSError, ValueError):
+        return ""
+    return (pkg.get("scripts") or {}).get("dev", "")
+
+
+def frontend_argv(frontend, port):
+    """How to start the dev server on `port`.
+
+    A Next dev script normally pins the port itself (`next dev -H 0.0.0.0
+    -p 4100`), and a pinned CLI flag beats the PORT env var -- commander
+    only consults `.env("PORT")` when the flag is absent. Appending a second
+    `-p` moves it anyway: both argument parsers Next has shipped, `arg` and
+    `commander`, take the last occurrence of a non-variadic flag.
+
+    PORT is still exported alongside, for a dev script that leaves the port
+    unpinned and for anything downstream that reads it.
+    """
+    script = dev_script(frontend)
+    if "next" in script:
+        return ["npm", "run", "dev", "--", "-p", str(port)]
+    return ["npm", "run", "dev"]
+
+
+def make_scratch(backend):
+    """A temp working directory holding a copy of .env with PORT overridden.
+
+    The backend's app.js calls dotenv.config({ override: true }), so a shell
+    env var loses to .env. dotenv resolves its file from the working
+    directory, so moving the port means moving the cwd -- and it lives outside
+    the repo so that recording never writes there.
+    """
+    path = Path(tempfile.mkdtemp(prefix=SCRATCH_PREFIX))
+    path.chmod(0o700)
+    lines = (backend / ".env").read_text().splitlines()
+    replaced = False
+    for i, line in enumerate(lines):
+        if re.match(r"^\s*PORT\s*=", line):
+            lines[i] = f"PORT={BACKEND_PORT}"
+            replaced = True
+    if not replaced:
+        lines.append(f"PORT={BACKEND_PORT}")
+    target = path / ".env"
+    target.write_text("\n".join(lines) + "\n")
+    target.chmod(0o600)
+    return path
+
+
+class Leg:
+    """One recorded direction: a label and the pair of files it writes."""
+
+    def __init__(self, run_dir, stem, title):
+        self.stem = stem
+        self.title = title
+        self.jsonl = run_dir / f"{stem}.jsonl"
+        self.log = run_dir / f"{stem}.log"
+
+    def summarise(self):
+        total = failed = 0
+        try:
+            with open(self.jsonl, encoding="utf-8") as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    total += 1
+                    try:
+                        rec = json.loads(line)
+                    except ValueError:
+                        continue
+                    status = rec.get("response", {}).get("status")
+                    if status is None or status >= 400:
+                        failed += 1
+        except FileNotFoundError:
+            pass
+        print(f"\n  {self.title}: {total} calls ({failed} failed).")
+        print(f"  Table   : {self.log}")
+        print(f"  Details : {self.jsonl}")
+
+
+def start_proxy(name, leg, listen_port, mode, cwd,
+                listen_host="127.0.0.1", show_host=False, skip=None):
+    """Start one recording mitmdump and register it for teardown."""
+    env = os.environ.copy()
+    env["MITM_RECORD_JSONL"] = str(leg.jsonl)
+    env["MITM_RECORD_LOG"] = str(leg.log)
+    if show_host:
+        env["MITM_RECORD_SHOW_HOST"] = "1"
+    if skip:
+        env["MITM_RECORD_SKIP"] = skip
+    argv = [
+        "mitmdump",
+        "--mode", mode,
+        "--listen-host", listen_host,
+        "--listen-port", str(listen_port),
+        "-s", str(Path(__file__).resolve()),
+        "-q",
+    ]
+    if mode.startswith("reverse"):
+        argv += ["--set", "keep_host_header=true"]
+    child = Child(name, argv, cwd, env)
+    children.append(child)
+    if not wait_for_port(listen_port, 30, child):
+        die(f"{name} recorder did not listen on :{listen_port}", child)
+    return child
+
+
+def proxy_env(env, port):
+    """Point a Node process's outbound HTTP at one of our forward proxies.
+
+    Node's global fetch honours the proxy variables only with
+    NODE_USE_ENV_PROXY (Node 24+); NODE_EXTRA_CA_CERTS is what makes it
+    trust mitmproxy's certificate for the HTTPS calls it intercepts.
+    """
+    env["NODE_USE_ENV_PROXY"] = "1"
+    env["HTTP_PROXY"] = f"http://127.0.0.1:{port}"
+    env["HTTPS_PROXY"] = f"http://127.0.0.1:{port}"
+    env["NODE_EXTRA_CA_CERTS"] = str(MITM_CA)
+    return env
+
+
+def main():
+    global scratch
+
+    parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    parser.add_argument("repo", help="path to the app repo")
+    parser.add_argument("--no-outbound", action="store_true",
+                        help="skip both forward proxies (:7102 Graph/Datalab, "
+                             ":4102 the frontend's own server-side calls)")
+    parser.add_argument("--no-frontend", action="store_true",
+                        help="leave the dev server on :4100 unrecorded, as it "
+                             "was before the frontend legs existed")
+    parser.add_argument("--frontend-all", action="store_true",
+                        help="keep /_next/static and other dev-server noise in "
+                             "the frontend recording instead of dropping it")
+    args = parser.parse_args()
+
+    repo = Path(args.repo).expanduser().resolve()
+    if not repo.exists():
+        print(f"repo not found: {repo}", file=sys.stderr)
+        return 2
+    backend, frontend = repo / "Backend", repo / "Frontend"
+
+    outbound = not args.no_outbound
+    record_frontend = not args.no_frontend
+    # Unrecorded, the dev server stays on the port the browser already calls.
+    frontend_port = FRONTEND_PORT if record_frontend else FRONTEND_PROXY_PORT
+    preflight(repo, outbound, record_frontend)
+
+    stamp = datetime.now().strftime("%Y%m%d-%H%M%S")
+    run_dir = WORKSPACE / workspace_slug(repo) / f"run-{stamp}"
+    run_dir.mkdir(parents=True, exist_ok=True)
+    (run_dir / "run.json").write_text(json.dumps({
+        "repo": str(repo), "started_at": datetime.now().astimezone().isoformat(),
+        "outbound": outbound,
+        "frontend": record_frontend,
+        "frontend_all": bool(args.frontend_all),
+    }, indent=2) + "\n")
+
+    be_in = Leg(run_dir, "backend-inbound", "into backend  (browser, frontend)")
+    be_out = Leg(run_dir, "backend-outbound", "out of backend  (Graph, Datalab)")
+    fe_in = Leg(run_dir, "frontend-inbound", "into frontend  (browser)")
+    fe_out = Leg(run_dir, "frontend-outbound", "out of frontend  (backend, external)")
+
+    def on_sigterm(*_):
+        raise KeyboardInterrupt
+
+    signal.signal(signal.SIGTERM, on_sigterm)
+
+    scratch = make_scratch(backend)
+
+    backend_env = os.environ.copy()
+    if outbound:
+        print(f"  Starting backend outbound recorder on :{OUTBOUND_PORT} ...", flush=True)
+        start_proxy("be-outbound", be_out, OUTBOUND_PORT, "regular", scratch, show_host=True)
+        backend_env = proxy_env(backend_env, OUTBOUND_PORT)
+        backend_env["NO_PROXY"] = "127.0.0.1,localhost"
+
+    print(f"  Starting backend on :{BACKEND_PORT} ...", flush=True)
+    backend_child = Child("backend", ["node", str(backend / "src" / "server.js")],
+                          scratch, backend_env)
+    children.append(backend_child)
+    if not wait_for_http(f"http://127.0.0.1:{BACKEND_PORT}/health", 90, backend_child):
+        die(f"backend did not become healthy on :{BACKEND_PORT}", backend_child)
+
+    print(f"  Starting backend recorder on :{PROXY_PORT} ...", flush=True)
+    proxy = start_proxy("be-proxy", be_in, PROXY_PORT,
+                        f"reverse:http://127.0.0.1:{BACKEND_PORT}", scratch,
+                        listen_host="0.0.0.0")
+    if not wait_for_http(f"http://127.0.0.1:{PROXY_PORT}/health", 30, proxy):
+        die(f"recorder did not proxy :{PROXY_PORT} -> :{BACKEND_PORT}", proxy)
+
+    frontend_env = os.environ.copy()
+    frontend_env["PORT"] = str(frontend_port)
+    if record_frontend:
+        # Bound before the dev server starts, so the port the browser calls is
+        # never briefly free during the first compile.
+        print(f"  Starting frontend recorder on :{FRONTEND_PROXY_PORT} ...", flush=True)
+        start_proxy("fe-proxy", fe_in, FRONTEND_PROXY_PORT,
+                    f"reverse:http://127.0.0.1:{FRONTEND_PORT}", scratch,
+                    listen_host="0.0.0.0",
+                    skip=None if args.frontend_all else FRONTEND_NOISE)
+        if outbound:
+            print(f"  Starting frontend outbound recorder on :{FRONTEND_OUTBOUND_PORT} ...",
+                  flush=True)
+            start_proxy("fe-outbound", fe_out, FRONTEND_OUTBOUND_PORT, "regular",
+                        scratch, show_host=True)
+            frontend_env = proxy_env(frontend_env, FRONTEND_OUTBOUND_PORT)
+            # Only the frontend's own two ports are excluded, not all of
+            # loopback: a server component calling the backend on :7100 is
+            # exactly what this leg exists to catch. Entries carry a port
+            # because undici matches NO_PROXY on host and port both.
+            frontend_env["NO_PROXY"] = ",".join(
+                f"{host}:{port}"
+                for host in ("127.0.0.1", "localhost")
+                for port in (FRONTEND_PROXY_PORT, FRONTEND_PORT)
+            )
+
+    print(f"  Starting frontend on :{frontend_port} ...", flush=True)
+    frontend_child = Child("frontend", frontend_argv(frontend, frontend_port),
+                           frontend, frontend_env)
+    children.append(frontend_child)
+    if not wait_for_port(frontend_port, 120, frontend_child):
+        die(f"frontend did not listen on :{frontend_port}", frontend_child)
+
+    print("  Warming up the first page compile (can take a minute) ...", flush=True)
+    # Straight at the dev server first. It binds its port well before it can
+    # answer, and a request landing in that gap fails -- through the recorder
+    # that failure is a row, so every frontend recording would open with a
+    # spurious ERR.
+    if not wait_for_http(f"http://127.0.0.1:{frontend_port}/", 180, frontend_child):
+        die(f"frontend never served a page on :{frontend_port}", frontend_child)
+    # Then once through the recorder, which proves the browser-facing chain
+    # before the banner claims it works.
+    if record_frontend and not wait_for_http(
+            f"http://127.0.0.1:{FRONTEND_PROXY_PORT}/", 30, frontend_child):
+        die(f"recorder did not proxy :{FRONTEND_PROXY_PORT} -> :{FRONTEND_PORT}",
+            frontend_child)
+
+    legs = [be_in]
+    if outbound:
+        legs.append(be_out)
+    if record_frontend:
+        legs.append(fe_in)
+        if outbound:
+            legs.append(fe_out)
+
+    width = max(len(leg.title) for leg in legs)
+    leg_lines = "\n".join(
+        f"  {leg.title:<{width}} : {leg.log}" for leg in legs)
+    disabled = []
+    if not record_frontend:
+        disabled.append("frontend legs off (--no-frontend)")
+    if not outbound:
+        disabled.append("outbound legs off (--no-outbound)")
+    if record_frontend and not args.frontend_all:
+        disabled.append("frontend static assets dropped (--frontend-all keeps them)")
+
+    print(f"""
+  Recording active on {len(legs)} leg(s).
+
+  Open:  http://localhost:{FRONTEND_PROXY_PORT}
+
+  VS Code must be forwarding:  {FRONTEND_PROXY_PORT} (app)  {PROXY_PORT} (api)
+  Both now front a recorder; both were already forwarded before this script
+  ran, so there is nothing new to add.
+
+  Repo    : {repo}
+  Run dir : {run_dir}
+
+{leg_lines}
+
+  Each table has a .jsonl beside it holding the full bodies.
+{("  " + "; ".join(disabled) + chr(10)) if disabled else ""}
+  Files contain live tokens and passwords. Do not share or commit.
+  Live view:  tail -f {be_in.log}
+  Ctrl-C to stop.
+""", flush=True)
+
+    exit_code = 0
+    try:
+        while True:
+            for child in children:
+                if not child.alive():
+                    print(f"\n  {child.name} exited unexpectedly.", file=sys.stderr)
+                    exit_code = 1
+                    raise KeyboardInterrupt
+            time.sleep(1)
+    except KeyboardInterrupt:
+        pass
+
+    cleanup()
+    for leg in legs:
+        leg.summarise()
+    print("\n  These files contain live tokens and passwords. "
+          "Do not share or commit.\n")
+    return exit_code
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except KeyboardInterrupt:
+        sys.exit(130)
+    finally:
+        cleanup()